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This is a programmer’s book about Windows programming. This book is not a 
tutorial, nor is it a compendium of tricks and wizardry. Instead, it is a collection 
of variations on a basic theme: The way to design Windows applications is to un- 
derstand the design of the Windows environment itself. 


My own experience with Windows programming grew out of my previous work 
with computer-video subsystems. In the mid-1980s, I spent several years devel- 
oping application interfaces to IBM PC and PS/2 video systems, but I began to 
change my approach to application interface development when I started work- 
ing with the Apple Macintosh and with Microsoft Windows. 


I was initially not impressed with the Windows environment. In version 1 (1985), 
Windows’ visual interface had a clunky, unconvincing appearance (Figure I-1). 
Worse, application development was an unpleasant experience without a robust 
debugger or insightful documentation. With version 2 (1987), Windows’ ap- 
pearance improved (Figure I-2), as did the development and debugging tools 
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Figure I-1. 

The user interface of Windows version 1, Microsoft's 
first graphical interface for IBM-compatible 
microcomputers. 
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Figure I-2. 

The user interface of Windows version 2, which 
introduced overlapping windows and support for 
high-resolution video displays. 


in the Windows Software Development Kit. Probably the best thing about this 
version of Windows was the publication of Charles Petzold’s encyclopedic Pro- 
gramming Windows book (Microsoft Press, 1990), which does a great job of 
describing the fundamentals of programming in the Windows environment. 


Windows finally began to reach its potential with version 3 (1990), which in- 
troduced a new and further-improved visual appearance (Figure I-3). This ver- 
sion of Windows also solved some of the memory-management limitations of 
previous versions by running in protected mode on Intel 80286 and 80386 
microprocessors. Most important, Windows 3 seemed to capture the imagination 
of application programmers. Many more commercial and public-domain applica- 
tions have been written for Windows version 3 than for both of the previous 
versions. 


As more people become involved in writing Windows programs, I think it 
makes sense to take a close look at the Windows environment from a software- 
design point of view. My goal in this book is to give you the ideas and the details 
you need to feel comfortable designing Windows applications. 
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Figure I-3. 

The user interface of Windows version 3, which uses 
proportionally spaced fonts and three-dimensional 
buttons and icons. 


Using This Book 

This is not a book for beginners. I assume that you know how to write a com- 
puter program, that you don’t mind using the C programming language, and that 
you are somewhat familiar with the Windows programming environment. If 
you’ve never written a Windows application in C, you can use this book to learn 
about the design and structure of Windows programs, but you will find the 
source-code examples more useful if you already have some experience in 
designing Windows programs. 


I don’t intend this book to replace Microsoft’s Windows Software Development 
Kit (SDK). The documentation supplied with the SDK is professionally written 
and thorough. You will certainly want to refer to it as you read about Windows 
and develop your own Windows applications. 


It goes without saying that this book will be most useful if you have a set of 
robust software-development tools for Windows. Equally important, you need 
the documentation that describes the details of the Windows programming envi- 
ronment. As I wrote this book, I frequently referred to the manuals in the SDK 
and to my copy of Petzold’s Programming Windows. You can’t program in Win- 
dows unless you have good programming tools and thorough documentation. 
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You should also have a computer system that is powerful enough to let you write, 
run, and debug Windows programs. A minimal Windows development system is 
an 80286-based machine with a hard disk, at least 2 MB of memory, a VGA- 
compatible video subsystem, and a mouse. I used such a system—an IBM PS/2 
Model 60—to develop many of the source-code examples in this book. How- 
ever, the faster your computer, the less time you'll spend waiting for it to compile 
and link your applications. 


You also need a Windows-compatible C compiler and linker. Microsoft’s C com- 
piler is still the most-used language translator for Windows applications, al- 
though a number of software vendors have introduced Windows-compatible 
compilers for C and for other high-level languages. The source-code examples in 
this book were created with Microsoft C, so you may have to work around some 
source-level incompatibilities if you compile the examples with another vendor’s 
compiler. 


In addition to a suitable computer system and a compiler, you should also have a 
set of Windows software-development tools, including a debugger and a dialog 
editor. In writing this book, I used the tools provided in Microsoft’s SDK. By the 
time you read this, however, a number of other software vendors will also have 
released useful Windows development products. 


How This Book Is Organized 


The first chapter of this book gives you a bird’s-eye view of the Windows envi- 
ronment. It emphasizes the important structural and functional components of 
Windows and shows how an application’s design is based on the need to interact 
effectively with the Windows environment. 


Chapter 2 is an overview of debugging in Windows. This chapter is the result of 
dozens of close encounters with foul and insidious bugs. It describes a variety of 
obvious and not-so-obvious bugs that could be lurking in your programs and 
suggests how you can detect and correct them. 


Chapters 3 and 4 explore the programming of dynamic link libraries (DLLs) in 
Windows. Chapter 3 reviews the structure of DLLs in Windows. It covers some of 
the details of memory management, parameter passing, and the use of resources 
in DLLs. Chapter 3 lays the groundwork for Chapter 4, which focuses on a natural 
application of DLLs—namely, support for custom-control classes. 


Chapter 5 examines Windows’ object-oriented heritage. The Windows environ- 
ment was designed by foresighted programmers who recognized the value of 
object-oriented concepts in a graphical windowing environment. This chapter 
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describes some object-oriented features of the Windows environment and sug- 
gests how Windows programs can benefit from object-oriented design. 


Chapter 6 digs into Dynamic Data Exchange (DDE), Windows’ protocol for inter- 
process communication. This chapter starts with an introduction to the client- 
server transaction model used in DDE. It then describes the message-based DDE 
protocol with an emphasis on the design of DDE transactions. This discussion 
leads naturally into the heart of the chapter—the DDE Management Library 
(DDEML). The chapter ends by considering some of the software design issues 
common to DDE programming. 


Chapter 7 is a collection of typical Windows programming problems and solu- 
tions. The chapter describes some advanced programming techniques that are 
not really part of Microsoft’s SDK documentation. There are no tricks or secrets 
here—just reasonable approaches to some programming puzzles that many 
Windows programmers will face sooner or later. 


Source-Code Notes 


I used Microsoft’s Windows Software Development Kit, version 3.0, to build the 
source-code examples in this book. All the source-code examples were com- 
piled with Microsoft C 6.0 (aka Microsoft C Professional Development System). 
The source code was tested in real, standard, and 80386 enhanced modes on 
several different computers, including an IBM PC/AT and IBM PS/2 models 60 
and 70. 


I have done my best to pare the source-code examples in this book to the 
minimum necessary to illustrate the techniques described in each chapter. None 
of the source code really represents a complete and polished Windows applica- 
tion. The most valuable part of a Windows application—the visual design, the 
flow of interactions with the user, the menus, and help text—can only be sup- 
plied by you. 


If you see ways to improve on the techniques I’ve described, if you derive new 
applications from the source-code examples in this book, or if you spot bugs that 
need to be fixed, I’d like to hear about them. Please contact me at this address: 


Microsoft Press 

Attention: Windows: Developer’s Workshop editor 
One Microsoft Way 

Redmond, WA 98052-6399 
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Windows Design 


1: WINDOWS DESIGN 


Although the Windows operating environment runs under MS-DOS, writing a 
Windows program is not the same as writing an MS-DOS program. It is unusual 
for a Windows program to call an MS-DOS function directly. Instead, Windows 
applications rely on the Windows application program interface (APD to obtain 
keyboard and mouse input, to produce output on a video display or printer, and 
to manage disk files. 


In fact, the key to writing a successful Windows application lies in taking full ad- 
vantage of Windows’ built-in functionality. This may seem a daunting proposi- 
tion in a programming environment that provides over 600 built-in functions. 
The way to grasp this wealth of built-in application support is to visualize how 
the Windows environment is put together. 


The Structure of the Windows Environment 


As you design a Windows program, you can rely on the Windows environment to 
provide three kinds of fundamental services. One is to perform basic input and 
output functions for the keyboard, mouse, video display, printers, disk files, and 
serial communications devices. Most of these functions are also supported to 
some extent in MS-DOS, but Windows’ basic input/output (I/O) functions are 
much more comprehensive than those in MS-DOS. Windows’ I/O functions are 
also designed to be device-independent. Hundreds of I/O devices are supported 
by Windows through a single set of API functions. Because of this power and 
generality, Windows programs almost always rely exclusively on the built-in API 
functions for input and output. 


Another of Windows’ fundamental jobs is to manage memory. Windows lets a 
program dynamically allocate and free blocks of memory. Windows’ memory- 
management API gives programs transparent access both to expanded memory 
(bank-switched memory conforming to version 4.0 of the LIM EMS standard— 
the Lotus-Intel-Microsoft Expanded Memory Specification standard) and to ex- 
tended memory (memory addressable above 1 MB). Windows also provides 
transparent support for virtual memory (sharing available memory by swapping 
blocks of memory to disk) in 80386-based and 80486-based computers. 


Windows’ third important service is to support multitasking—that is, to allow 
two or more programs to share the CPU, memory, and I/O hardware. The fact 
that Windows allows multitasking means that Windows’ I/O and memory- 
management functions accommodate the need for different programs to share 
resources cooperatively. 
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You can imagine the Windows environment to be structured as a set of “man- 
agers” that are responsible for supporting I/O, memory management, and multi- 
tasking. In fact, Windows programmers refer to the “I/O manager,” the “memory 
manager,” the “task manager,” and the “window manager” as if.they were 
discrete components of Windows. Although this is a convenient conceptual 
model, these functions correspond only roughly to separate modules in the Win- 
dows environment. 


In Windows, a module is any collection of executable code or data that can be 
loaded into memory. A module might contain a user-written application, a hard- 
ware device driver, or a dynamic link library (DLL) of functions or data resources 
that a program contained in another module can access. In Windows applica- 
tions, as in the Windows environment itself, support for complex operations is 
often distributed across several Windows modules. 


Windows itself is built from a number of interrelated modules. The Windows API 
functions are implemented in a set of modules that are loaded into memory 
when Windows starts up. These modules are shown in Figure 1-1. The three 
main modules are GDI.EXE; USER.EXE; and KERNEL.EXE, KRNL286.EXE, or 
KRNL386.EXE (depending on whether Windows is running in real, standard, or 
enhanced mode). These three modules contain most of the API functions. The 
remaining functions, which are used for accessing I/O hardware, are supported 
in a set of device-driver modules (COMM.DRV, KEYBOARD.DRYV, and so on). 


To write a Windows application, however, you rarely need to worry about the 
names of the modules that make up the Windows environment. Your programs 
can call any Windows API function regardless of which module contains the 
function. Usually, the only modules you need to work with explicitly are the ones 
that you write—that is, the modules that contain your application programs and 
DLLs. 


Windows has the ability to load a module dynamically at the time an executing 
program needs to access the module’s functions or data. Windows supports sev- 
eral API functions (LoadLibrary, LoadModule, and WinExec) that let a program 
explicitly load a module at the time the program executes. Windows can also 
load a module implicitly if another program refers to a function within the mod- 
ule. Such implicit dynamic binding between functions in different modules relies 
on the notion of exported and imported functions. 
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Module Functions Supported 

GDIEXE Graphics device interface: output of graphics 
images, color-palette management 

USER.EXE Window, icon, and cursor management 

KERNEL.EXE (real mode) Memory management, task scheduling 


KRNL286.EXE (standard mode) 
KRNL386.EXE (enhanced mode) 


COMM.DRV Device driver for serial communications 
KEYBOARD.DRV Device driver for keyboard 

MOUSE.DRV Device driver for mouse 

SOUND.DRV Device driver for sound generation 
SYSTEM.DRV Device drivers for system timer, disk drives 
Figure 1-1. 


Modules in the Windows environment. In addition to these main modules and 
device drivers, additional device drivers for video displays, networks, and 
other hardware can be installed. 


Most Windows modules that contain executable code implement one or more 
functions that can be called by code in other modules. Such functions are known 
as exported functions. The module that contains the function’s executable code 
exports the function; a module that calls the function imports the function. Ex- 
ported functions are the only functions in a module that can be called by pro- 
grams in other modules. 


Exported functions are used extensively both within Windows itself and in Win- 
dows applications» The entire Windows API consists of functions that are ex- 
ported from the various modules that make up the Windows environment. 
Moreover, Windows expects applications to define exported functions that Win- 
dows itself will call. In particular, Windows calls certain functions exported 
from an application to direct keyboard and mouse input to the application and to 
facilitate multitasking. 


Tasks and Instances 


Windows supports cooperative multitasking. Windows’ task manager maintains 
a list of tasks and keeps track of the order in which the tasks execute. When 
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Windows transfers control to a task, other tasks cannot run until the task in con- 
trol explicitly yields control to the task manager. Windows’ cooperative multi- 
tasking scheme differs from a preemptive multitasking implementation such as 
the one used in OS/2. Under preemptive multitasking, the operating system exe- 
cutes each task in turn for a predetermined amount of time and switches from 
task to task regardless of whether the tasks themselves yield control to the 
operating system. 


Windows executes different applications as different tasks. Also, when you run 
two or more instances of an application at once, Windows executes each in- 
stance of the application as a separate task. Windows loads a separate, unshared 
copy of the application’s default data segment into memory for each instance. 
Task-specific data, including the stack and local data, are stored in the data seg- 
ment that corresponds to each instance of an application. 


Although Windows loads a copy of the module’s default data segment for each 
instance of the module, there is only one copy of a module’s executable code in 
memory regardless of how many instances are running. For this reason, execut- 
able code and data are strictly segregated in a Windows application. You must 
pay careful attention to this requirement if you are programming in assembly 
language, but separating code and data is not a concern if you use a high-level 
language translator such as the Microsoft C compiler to generate the executable 
code for your applications. 


Furthermore, Windows’ cooperative multitasking scheme imposes other con- 
straints on application design. For cooperative multitasking to work, each Win- 
dows application must be designed with at least one window function—a 
function that can be called by Windows’ task manager—and a message loop that 
yields control to the task manager. (See the next section for a discussion of mes- 
sages.) This particular requirement is important because it imposes a certain 
logical structure on all Windows applications. 


Figure 1-2 illustrates the flow of a Windows application that cooperates properly 
with the task manager. The application’s central control structure is a loop in 
which the application carries out a time-limited action and then transfers control 
back to Windows’ task manager. The task manager allows other tasks to execute. 
It then transfers control back to the application to carry out another action. 


This structure is simple yet powerful. The key to its usefulness is that an applica- 
tion can carry out a different action each time it gains control from the task man- 
ager. Implicit in this design, however, is a mechanism for an application to 
determine which of a set of possible actions to carry out. In Windows, messages 
are the mechanism for doing this. 
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Task manager 
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Figure 1-2. 
Flow of control in a Windows application. 


Messages 


In the Windows environment, a message is a stereotyped set of data that is 
passed through a function call from Windows to an application’s window func- 
tion. The function call always uses the set of parameters that is shown in Figure 
1-3 on the following page. The second parameter is a value that identifies the 
message. The Microsoft Windows Software Development Kit (SDK) associates 
symbolic names with message identifiers. Symbolic names such as WM- 
CREATE, WM_COMMAND, and WM_PAINT suggest how the messages they 
identify are to be interpreted by the application that receives them. (The Win- 
dows SDK documentation details all of the messages and their parameters.) 


Windows’ use of messages might be construed as a kind of event-notification 
mechanism. Different events in the Windows environment give rise to different 
messages. Some events are intuitively obvious. For example, when you click a 
mouse button or press a key on the keyboard, Windows uses one or more mes- 
sages to indicate exactly which mouse or keyboard activity has occurred. That is, 
Windows calls an application’s window function with message-identifier values 
such as WM_LBUTTONDOWN, WM_MOUSEMOVE, or WM_KEYDOWN. The 
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LONG PASCAL FAR . 
WndFn( HWND hWnd, WORD wMsg, WORD wParam, LONG 1Param ) 
{ 


/* hWnd: Window handle 

wMsg: Message identifier 

wParam: Usage depends on the value of wMsg 

lParam: Usage depends on the value of wMsg */ 

} 

Figure 1-3. 
A C-language declaration of a message-processing function in a Windows 
application. 


application responds to each message by processing the mouse-location or key- 
stroke information in the associated parameters wParam and IParam. 


Windows also uses certain messages to notify an application to take specific ac- 
tions. For example, Windows uses the WM_PAINT message to notify an applica- 
tion to produce output on the video display. An application responds to this 

particular message by calling the Windows API functions that draw text or 
graphics on the screen. Windows uses other messages to notify an application 
about changes in the state of the Windows environment and to facilitate direct 
communication between different applications. 


To pass a message to an application, Windows can either post the message to an 
application-specific queue or send the message directly to a window function in 
the application. For example, messages that notify an application of keyboard or 
mouse input are always posted to the message queue. To process messages prop- 
erly, every application must contain a message loop that checks the queue peri- 
odically for the arrival of newly posted messages, as shown in Figure 1-4. The 
Windows API provides a set of functions (GetMessage, PeekMessage, Wait- 
Message) that do this efficiently. 


In contrast, Windows sends messages such as window-management messages 
directly to an application, bypassing the application’s message queue. The differ- 
ence between the two message-passing methods is one of synchronization be- 
tween Windows and the application. When a message is posted to an 
application’s message queue, the application does not actually process it until 
Windows’ task manager returns control to the application. When a message is 
sent directly to an application, the application processes it immediately. 
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int PASCAL WinMain( ... ) 


{ 
MSG msg; 


Initialize( ... ); 


/* yield to the task manager; loop until done */ 

while( GetMessage( &msg, ... ) ) 

{ 
TranslateMessage( &msg ); /* process the message */ 
DispatchMessage( &msg ); 

} 


return ... ; 


} 


Figure 1 ~4, 
A typical message-processing loop in a Windows application. Compare the flow 
of control in this example with the flowchart in Figure 1-2. 


Windows 


In the Windows environment, the entity that processes messages in an applica- 
tion is a window. There are two logical components to a window, a data struc- 
ture that describes the window’s characteristics and a window function that 
processes messages. The data structure is created and maintained internally by 
Windows’ window manager. The window function is an exported function that 
can be called directly by Windows. 


Intuitively, the purpose of a window is to carry out the graphical processing re- 
quired to maintain a visual window on the screen. However, you might better 
regard a Windows window as a message-processing unit that does not necessari- 
ly have a visual component. An application can create a window whose purpose 
is only to do a specific message-processing job without ever appearing on the 
display screen. For example, an application that uses the message-based 
Dynamic Data Exchange (DDE) protocol to exchange messages with other appli- 
cations can create one or more “invisible” windows that encapsulate DDE mes- 
sage processing. 


Much of the power of Windows programming is based on the fact that an appli- 
cation can create multiple windows, each with a different function. Windows’ 
window manager facilitates this by maintaining a list of the windows created by 
all executing applications. The window manager associates windows with the 
tasks in which they are created. When a task terminates, the window manager 
destroys the windows that the task created if the task itself has not already 
destroyed them. . 
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Multiple windows in a task are organized in a hierarchy of owners and owned 
windows—that is, each window can be owned by another window, and each 
window can have one or more owned windows associated with it. These owner/ 
owned relationships affect both the lifetime of a window and the manner in 
which a window defined with particular styles is visually displayed, as shown in 
Figure 1-5. When a window has an owner, the window is destroyed implicitly if 
its owner is destroyed. Also, windows without owners can be overlapped by 
other windows, but owned windows are always displayed in front of their 
owners, as shown in Figure 1-6. 


A special owner/owned relationship exists for windows created with the 
WS_CHILD style. For example, a child window can be displayed only within the 
rectangular area defined by its parent (owner). Also, Windows’ window manager 
treats parent and child windows differently in regard to the kinds of messages 
they receive. In particular, Windows sends a notification message, 
WM_PARENTNOTIFY, to a parent window whenever a child window is created 
or destroyed. A child window uses a different message, WM_COMMAND, to no- 
tify a parent window that the child has processed user input. 


Visual Style Is Owner Lifetime Visual Relationships 
Specified? 
WS_OVERLAPPED No Task Overlaps other windows 
Always has caption and 
border 


CreateWindow can specify 
default location and size 


WSOVERLAPPED Yes Owner Overlaps owner 
Always has caption and 
border 
Not visible if owner is not 
visible 
WS_—POPUP No Task Overlaps other windows 
WS_POPUP _ Yes Owner Overlaps owner 
Not visible if owner is not 
visible 
WS_CHILD Yes Owner (parent) Clipped within parent 
Figure 1 =5. 


Characteristics of windows with different visual styles and owners. A window’s 
style and owner are specified at the time a window is created. 
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[Pop-up 1494 {no owner) La 
- 
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Figure 1-6. 

An example of the visual relationships of windows with and without owners. 
The overlapped window (13C8) owns both a pop-up window (1450) and a child 
window (140C). The child window is clipped by the owner, and the owned pop- 
up window overlaps the owner, but the pop-up without an owner (1494) can be 
overlapped by the other windows in the task. 


In the Windows environment, the processing necessary to keep track of window 
relationships is hidden from applications. Internally, the window manager main- 
tains a list of data structures, each of which identifies and describes a window. 
From an application’s point of view, however, each window is identified only by 
a unique integer value assigned by the window manager. This identifying value 
is the window’s handle. 


Handles 


Windows are only one of a variety of items that are identified by handles in the 
Windows environment. The following items also use handles: 


Modules 

Tasks / 
Instances 

Files 

Blocks of memory 
Menus 


Controls 


Fonts 
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™ Resources (icons, cursors, strings, and so on) 


™ GDI objects (bitmaps, brushes, metafiles, palettes, pens, regions) and de- © 
vice contexts 


Windows programs do not use physical addresses to identify blocks of memory, 

files, tasks, or dynamically loaded modules. Instead, the Windows API identifies 

these items by assigning handles to them and passing the handle values to an 
- application. 


A Windows application can obtain a handle for a particular item in one of two 
different ways. Many API functions, including CreateWindow, GlobalAlloc, and 
OpenFile, return a handle. Also, Windows can pass a handle to an application as 
a parameter in a call to an exported function in the application. As you might in- 
fer from the variety of items that are identified by handles, you can expect to 
work with handles just about everywhere in the Windows environment. This 
pervasive use of handles affects the design of every Windows program. 


The value of a handle is meaningful only in that it uniquely identifies the item it 
represents. In general, handle values correspond to entries in a list of items, but 
only Windows itself can access the list directly. An application can usually access 
the item that a handle represents only by calling a Windows API function that 
specifically dereferences the handle. For example, an application can allocate a 
block of memory for its own use and obtain a handle to the block by calling.the 
API function GlobalAlloc: 


hMem = GlobalAlloc( ... ); 


The handle returned by GlobalAlloc identifies a particular block of memory to 
the application, but the application cannot use the handle to access the memory 
block directly. Instead, the application must call another API function, 
GlobalLock, which returns the physical address of the memory block: 


lpMem = GlobalLock( hMem ); 


Memory Management 


Windows’ memory manager controls all available system memory. It dynami- 
cally allocates and frees blocks of memory as needed for code and data segments 
from modules. The memory manager also supports a set of API functions that a 
Windows program can call to allocate blocks of memory for its own use. 
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From the point of view of a Windows program, the memory manager organizes 
available memory in two different heaps: a global heap and a local heap. The 
global heap encompasses all available memory. The memory manager allocates 
global memory on a segment-by-segment basis. For example, if an application 
contains two executable-code segments and one default data segment, Windows 
loads the three segments into three separate blocks of global memory. Similarly, 
each call to the API function GlobalAlloc allocates a block of memory that an ap- 
plication can access by using a far pointer. 


The local heap consists of memory in a module’s default data segment, which is 
allocated from the global heap when the module is loaded into memory. A pro- 
gram can call LocalAlloc to allocate blocks of memory in the local heap. These 
memory blocks are addressable as near data. Because a module’s local heap 
shares a single memory segment with the module’s stack and static data vari- 
ables, the amount of data that can be stored in the local heap is limited by the 
size of a physical segment in memory (64 KB) and the amount of memory used 
by the stack and static variables. 


The essential difference between the local and global heaps is one of scale. The 
local heap is best for containing small amounts of data used only in a single in- 
stance of an application. Use the global heap for large memory blocks and for 
data shared among two or more modules. 


The Structure of a Windows Application 


All Windows applications bear a certain resemblance to each other. This is be- 
cause the structure of a Windows application is mostly determined by the need 
for it to interact smoothly with the Windows environment. To build a Windows 
program, you use the structural components that characterize the Windows en- 
vironment: modules, functions, tasks, instances, messages, windows, handles, 
and dynamically allocated memory. 


You can see this in the structure of the sample application in Figure 1-7 on the 
following page. The actions the program carries out actually have little to do 
with the program’s design. If a different programmer had written this program, 
you would notice differences in style, but the flow of control and the modular 
structure of the application would be pretty much the same. 
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FORE AH HT EEE HERR ESHER ERE HERE EHH EREE SHER ESHER RES HH REESE HERE EH HEHEHE EREE EERE EE HE 


# * 
# NMAKE description for MODSTAT.EXE * 
# ; * 


EHH Hee RARER E HERE EE ERE REE SHEE EEE H EE ERE EERE H EERE EOE REE THERES ROHR ER SEHR REE E EEE 
.C.0bj: 
cl /AM /c /G2sw /Osw /W4 /Zlp $*.c 
ALL: modstat .exe 
modstat .obj: modstat.c modstat.h 


modstat.res: modstat.rc modstat.h modstat.ico 
re /r modstat.rc 


modstat .exe: modstat.obj modstat.res modstat.def 


link /al:16 /nod /noe modstat, , , libw mlibcew, modstat.def 
re modstat.res 


[AERA EERE EERE THERE EERE RHEE E REESE REESE ERE EE EEE EE RHEE ERTS EERE DEERE EEE EE EE Ot 


2 * 
* MODSTAT.C * 
* * 
* Exports: TopLevelWndFn . 
* WodEnunFn > 
* ; : * 


HERE ERER ESET REESE HER ERE HERE E EERE EEE EE ESE REPEL EARLE HERE HE REPRE ER HERE HED / 


#define NOCOMM 

#include <windows .h> 

#include <string.h> /* contains strrcehr and strchr */ 
#include "modstat .h" 


/*** FUNCTION PROTOTYPES ***/ 


LONG PASCAL FAR TopLevelWndFn( HWND, WORD, WORD, LONG ); 
BOOL PASCAL FAR WndEnumF'n( HWND, DWORD ); 


static HWND Init ( HANDLE, HANDLE, int ); 
static void MsgCommand( HWND, WORD, LONG ); 


Figure 1-7. (continued) 
Source code for MODSTAT.EXE. 
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Figure 1-7. continued 


static void MsgPaint ( HWND ); 
static void ShowModuleInfo( HDC ); 


/*** GLOBAL VARIABLES ***/ 


char szTopLevelClass[] = "ModStat:TopLevel"; 
char szAppTitle[] = "System Modules"; 
HANDLE hInstance = 0; 


int nCharX, nCharyY; 
struct 
{ 
int CX; 
int CY; 
} 
CharSize; 


I bk Ekek eh tekeh hehetetdehehahetetekehehetetetekehcteltekehtekehehettedakketeiekekeksheksttekekehehtekeheietekehettelelehstekeketetettetele 


* * 
* WinMain * 
* * 


PORE NER HEHE EERE EEE EET EEE HEHEHE E PEER EERE ETHERS EATER SERRE HEHEHE ERK E EERE / 


int PASCAL 
WinMain( HANDLE hInst, HANDLE hPrevinst, LPSTR lpszCmdLine, int nCmdShow ) 


{ 
HWND hWnd; 


MSG msg; 


hWnd = Init( hInst, hPrevInst, nCmdShow ); 
if( 'hWnd ) 
return 0; 


while( GetMessage( &msg, 0, 0, 0) ) 


{ 
TranslateMessage( &msg ); 


DispatchMessage( &msg ); 
} 


return msg.wParam; 


(continued) 
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Figure 1-7. continued 


[OH PER SHEE EER EEE ED EEE RSH EEEE SHORES HE EEE FEELS TEESE HEH ORE ESHER RESSR EEE EHH EERO HEE 


2 PERLE SES be * 
eae : ae : _ . ; 
* Poe a 


CPRTREFERERH SE EES EEE PEN SERAPH OE RESP SE HESS EDR E ERE REE HE REDE E EERE EER ER ERE EEE ED / 


static HWND Init( HANDLE hInst, HANDLE hPrevInst, int nCmdShow ) 


{ 
WNDCLASS we; 
EWND hWnd; 
HDC hoc; 


TEXTMETRIC tm; 


if( hPrevInst ) 


{ 
/* copy global data from previous instance */ 
GetInstanceData( hPrevInst, (NPSTR)&CharSize, sizeof CharSize ); 
} 
else 
{ 
/* rvegister the top-level window class */ 
we. lpszClassName = szTopLevelClass; 
we. hinstance = hInst; 
we.lpfnWndProc = TopLevelWndFn; 
we. hCursor = LoadCursor( 0, IDC_ARROW ); 
we. hIcon = LoadiIcon( hInst, "TopLevellIcon" ); 
we. 1lpszMenuName = "TopLevelMenu"; 
we .hbrBackground = COLOR_WINDOW+1 ; 
we.style = CS_HREDRAW | CS_VREDRAW; 
we .cbClsExtra = 0; 
we. cbWndExtra = Q; 
if( !RegisterClass( éwe ) ) 
return 0; /* return 0 if unsuccessful +*/ 
/* save the default character dimensions */ 
hDC = CreateDC( "DISPLAY", NULL, NULL,. NULL ); 
GetTextMetrics( hDC, &tm ); 
DeleteDC( hDC ); 
CharSize.CX = tm.tmAveCharWidth; 
CharSize.CY.= tm.tmHeight + tm.tmExternalLeading; 
} : . ; 


/* save the current instance handle in a global variable +/ 
hInstance = hInst; arnt : 


(continued) 
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Figure 1-7. continued 


/* create and display a top-level window */ 
hWnd = CreateWindow( szTopLevelClass, 
szAppTitle, 
WS_OVERLAPPEDWINDOW, 
CW_USEDEFAULT, 0, CW_USEDEFAULT, 0, 
0, 
0, 
hInstance, 
NULL ); 


ShowWindow( hWnd, nCmdShow ); 
UpdateWindow( hind ); 


return hWnd; 


[PARE EERE EERE EERE EE HERE EEE E RHO E EERE HER EEE EEE EERE EEE EE EEE THEE EEE R EH EEE HD 


* * 
* TopLevelWndFn . 


REEHH EERE EOE E EERE SEPA EEE REESE SHED ER HERE PEER ESE H EERE DEERE EEE E EER H ERE HE REED / 


LONG PASCAL FAR 
TopLevelWndFn( HWND hWnd, WORD wMsg, WORD wParam, LONG lParam ) 
{ 

LONG 1RVal = OL; 

BOOL bDWP = FALSE; 


switch( wMsg ) 


{ 
case WM_PAINT: 


MsgPaint ( hWnd ); 
break; 


case WM_COMMAND: 
MsgCommand( hWnd, wParam, lParam ); 
break; 


case WM_DESTROY: 
PostQuitMessage( 0 ); 
break; 

default: 


bDWP = TRUE; 
break; - 


(continued) 


17 


Windows: Developer’s Workshop 


Figure 1-7. continued 


if( DDWP ) BEE EEUS a 
1RVal = DefWindowProc( hWnd, wMsg, wParam, lParam ); 


return 1RVal; 


‘e 


[HERE E EEE EE TREE EER EHR EEE EERE ER ER EERE ER EE EERE EER EE EEE EERE EES R REESE HEHEHE HEE EH HE 


* * 
* MsgCommand * 


PERRET EEE EEE E HEHE LER EE EEE HER EERE HEEFT ARES SE TEER HERES HERR ETHER ERE HERR E SEES / 


static void MsgCommand( HWND hWnd, WORD wParam, LONG lParam ) 
{ 


switch( wParam ) 


{ 
case IDM_ENUM: 
InvalidateRect ( hWnd, NULL, TRUE); 
break; : 


default: 
break; 


[HARE HERR EEE HEE EEE EERE E HERAT EH ERE EERE RES H SHEET HERETO HERE EE HERE ER EERE ER ER EEE HE 


* 
* MsgPaint + 
* # 


REHOHEREE HEHE EH EH EEE E EEE SESH ESSE SE REDEEOESESEREE SEER EE DEERE ERE H RRS EHR REE H EES | 


static void MsgPaint ( HWND hWnd ) 
{ 


HDC hDC; 

PAINTSTRUCT ps; 

InvalidateRect (hWnd, NULL, TRUE ); /* update the entire client area */ ; 
hDC = BeginPaint( hWnd, é&ps ); 


» ShowModuleInfo( hDC ); 
EndPaint( hWnd, &ps ); 


(continued) 
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Figure 1-7. continued 


[REPRE H REET ERE T EERE REET E REED EE EERE EERE SEER EH EEE E SHEE EE ER HEHE REE EE HSER EE HOHE 


* 


* ShowModuleInfo * 


* 


ee ee he tne 


static void ShowModuleInfo( HDC hDC ) 


{ 


FARPROC pEnumFn; 

char szBuf [80] ; 

HANDLE hModule; 

char szModuleName [12] ; 

int nRefCount ; 

static char szOtherInst[] = "Other instances of this application"; 


/* display task and instance information */ 

wsprintf( szBuf, "This is one of %d currently executing tasks.", 
GetNumTasks() ); 

nCharX = CharSize.Cx; 

nCharY = CharSize.CyY; 

TextOut( hDC, nCharX, nCharY, szBuf, lstrlen(szBuf) ); 


wsprintf( szBuf, "Task handle: %04X Instance handle: %04X", 
GetCurrentTask(), hInstance ); 

nCharY += CharSize.Cy; 

TextOut( hDC, nCharX, nCharY, szBuf, lstrlen(szBuf) ); 


/* display module handle, name, and reference count */ 

GetModuleFileName( hInstance, szBuf, sizeof szBuf }); 

istrepy( szModuleName, strrchr( szBuf, '\\' )+1 ); 

*(strchr( szModuleName, '.' )) = 0; 

hModule = GetModuleHandle( szModuleName ); 

nRefCount = GetModuleUsage( hModule ); 

wsprintf( szBuf, "Module handle: %04X Name: %s Reference count = %d", 
hModule, (LPSTR)szModuleName, nRefCount ); 

nCharY += CharSize.Cy; 

TextOut( hDC, nCharX, nCharY, szBuf, lstrlen(szBuf) ); 


if( nRefCount > 1 ) 


{ 
nCharY += 2 * CharSize.Cy; 


TextOut( HDC, nCharX, nCharY, szOtherInst, (sizeof szOtherInst) - 1); 


(continued) 
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Figure 1-7. continued 


/* enumerate other instances of this application */ 

pEnumFn = MakeProcInstance( (FARPROC)WndEnumFn, hinstance ); 
EnumWindows( pEnumFn, MAKELONG(hModule, hDC) ); 
FreeProcInstance( pEnumFn ); 


[ERA e RRR E EERE TERRE ERE E HEE EERE EERE EEE REE EERE EERE EERE EER EERE ESHER EERE RHEE E 


* 


* 


* WndEnumFn * 


* 


* 


PHAR EREERE HERES EEE EEE E EEE RE REE ERE E EERE REE HEEEHHE RET HERE ET HEHEHE ERE EH OD / 


BOOL PASCAL FAR WndEnumFn( HWND hWnd, DWORD dwParam ) 


{ 
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char szBuf [64]; 
HANDLE hiInst; 
HANDLE. hModule; 


/* determine the module name for this window */ 
hIinst = GetWindowWord( hWnd, GWW_HINSTANCE ); 
GetModuleFileName( hInst, szBuf, sizeof szBuf ); 
lstrcepy( szBuf, strrchr( szBuf, '\\' )+1 ); 
*(strchr( szBuf, '.' )) = 0; 


hModule = GetClassWord( hWnd, GCW_HMODULE ); 


_/* display task, module, and instance handle for other instances */ 


if( (hModule == LOWORD(dwParam)) && (hinst != hInstance) ) 
{ 
wsprintf( szBuf, "Task handle: %04X Instance handle: %04X", 
GetWindowTask( hWnd ), hInst ); 
nCharY += CharSize.Cy; 
TextOut ( HIWORD(dwParam), nCharX, nCharY, szBuf, lstrlen(szBuf) ); 


} 


return TRUE; 
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Figure 1-7. continued 


[RARER EERE EEE EEE REE REE EE EEE TERE EERE E ERE E RHEE EERE R EERE EE EEE EERE EEE HE 


* . * 
* MODSTAT.RC resource script ‘ 
* * 


PEER EE RETR EEE E THERE EER EEE SHEE EEE E EEE HEEL EE EEEH EHS E RR RE HERR REESE RHEE RH ED / 


#include "modstat.h" 


/* icon */ 
TopLevelicon ICON modstat.ico 


/* menus */ 
TopLevelMenu MENU 


{ 
MENUITEM "&Enumerate" IDM_ENUM 


Ee ee ee eae ee ee de 


* ; * 


* MODSTAT.H ss 
* Header file for MODSTAT.C * 
* * 


PEPER PRES ERSTE STEER ETERS HERE E EEE EE ESET ESTEE REET DRE E EEE EEE EEA EERE ERE HERE ED / 


#define IDM_ENUM 101 


PASSER HHEAEEHE EERE HREEEHHEERHHERE EP HEEREH HERES HEHEHES HEHEHE EHH REE EAAHEEE EE ER EEE 


. * 
? 


; MODSTAT.DEF module-definition file * 


« * 
, 
PRPHEERREE ERE EEE EE EEE HERR EEE EER EH HERE HH ERE EEE HEHEHE HERE EERE HEHEHE EEE REE HH 


NAME MODSTAT 

DESCRIPTION "MODSTAT.EXE version 1.0' 
EXETYPE WINDOWS 

STUB ‘WINSTUB.EXE' 

CODE LOADONCALL MOVEABLE DISCARDABLE 
DATA PRELOAD MOVEABLE MULTIPLE 


(continued) 


21 


Windows: Developer’s Workshop 


Figure 1-7. continued 


SEGMENTS . _TEXT PRELOAD MOVEABLE DISCARDABLE 
HEAPSIZE 1024 
STACKSIZE 5120 
EXPORTS TopLevelWndFn 
WndEnumFn 


The sample application displays information about the modules loaded in 
memory. The application’s module name, MODSTAT, is specified in the NAME 
statement in the module-definition file. MODSTAT.DEF. The corresponding exe- 
cutable file is MODSTAT.EXE. The module exports two functions: TopLevel- 
WndFn and WndEnumFn. Both of these functions are compiled as far functions 
that use the Pascal convention for parameter-passing, and both are listed as ex- 
ports in the module-definition file. These functions are exported so that Win- 
dows itself can call them; the far and Pascal calling conventions are required for 
all exported functions that can be called by Windows. 


Windows calls TopLevelWndFn to process messages for the application’s top- 
level window (its only window), and WndEnumFn in response to the applica- 
tion’s call to EnumWindows. A single call to EnumWindows causes Windows to 
call WndEnumFn once for each overlapped and pop-up window in the window 
manager’s list. 


If you run multiple instances of this application, you can see in each instance’s 
display the relationship between modules, tasks, and instances. Each time you 
invoke MODSTAT.EXE, Windows creates a new task and a new instance and 
assigns handles to each. All instances of the application, however, are associated 
with the same module and module handle. 


Initialization 

When you invoke MODSTAT.EXE, Windows loads the executable code and 
default data segment into memory. It then transfers control to a short initializa- 
tion function (named __astart in programs compiled with the Microsoft C com- 
piler) that initializes the application’s stack and local heap in the default data 
segment and then transfers control to WinMain. 
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WinMain 

Just as main is the function where a standard C program begins executing, Win- 
Main is the function where the execution of a Windows application begins. Usu- 
ally, WinMain’s first action is to perform the initialization required to support an 
instance of the application. In the example in Figure 1-7, WinMain calls a func- 
tion named Jnit to do this initialization. Jnit’s most important actions are em- 
bodied in its calls to RegisterClass and CreateWindow. The call to RegisterClass 
describes the default characteristics of the top-level window in the application. 
Init calls RegisterClass only for the first instance of the application. After the 
class has been registered, Windows maintains the class description internally so 
that subsequent instances of the application can refer to it. Windows discards the 
class description only when all instances of the application have terminated. 


From the point of view of program flow of control, the crucial data element in 
the call to RegisterClass is the address of TopLevelWndFn, which is assigned to 
we.lpfnWndProc. After Init calls CreateWindow to create a window using the 
registered class description, Windows can begin to call TopLevelWndFn to pro- 
cess messages. This is the key to understanding WinMain’s message loop, which 
follows the call to Init. . 


The Message Loop 


The message loop starts with a call to GetMessage. GetMessage retrieves a mes- 
sage from the application’s message queue and fills the msg data structure with 
the message identifier and parameters. If the queue is empty, the call to Get- 
Message gives Windows’ task manager a chance to transfer control to another 
task. The message loop thus serves a dual purpose: The application retrieves 
messages from its message queue, and Windows’ task manager regularly regains 
control and allows other tasks to execute. The message loop continues to exe- 
cute until GetMessage retrieves a WM_QUIT message from the application’s 
message queue. For this message, GetMessage returns 0, which causes the loop 
and the application to terminate. 


The message-loop functions TranslateMessage and DispatchMessage process 
each message that GetMessage retrieves from the message queue. The action 
of TranslateMessage is to translate the keyboard messages WM_KEYDOWN 
and WM_KEYUP into WM_CHAR messages. TranslateMessage also translates 
WM_SYSKEYDOWN and WM_SYSKEYUP messages (which are sent if the Alt 
key is down when another key is pressed) into WM_SYSCHAR messages. 
Although TranslateMessage is not strictly required for message processing, it is 
an essential component of the message loop in any program that expects key- 
board input. 
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DispatchMessage performs the vital function of transferring control to a window 
function. DispatchMessage uses the window handle that is part of each message 
to determine the address of the corresponding window function. In the 
MODSTAT sample program, the window function is TopLevelWndFn. Each time 
the message loop in WinMain executes DispatchMessage, Windows calls 
TopLevelWndFn with the message identifier and its corresponding parameters. 


GetMessage is one of the three Windows API functions that yield control to the 
task manager. The other functions— PeekMessage and WaitMessage—are most 
useful in a program that performs time-consuming or repetitive actions such as a 
prolonged computation or an I/O operation. PeekMessage is used in such a pro- 
gram instead of GetMessage because PeekMessage returns control to the pro- 
gram even if the message queue is empty. You can therefore use PeekMessage to 
design a message loop that frequently transfers control to Windows’ task man- 
ager so that other applications can execute in the midst of a prolonged computa- 
tion. The only constraint is that you split the prolonged computation into a series 
of time-limited steps, as the example in Figure 1-8 suggests. 


bDone = FALSE; 


do 


/* yield control and check the message queue */ 
if( PeekMessage( &msg, ... ) ) 
{ 
/* process a message */ 
if( WM_QUIT == msg.message ) 
‘bDone = TRUE; 


else 
{ 
TranslateMessage( &msg ); 
DispatchMessage( &msg ); 
} 
} 


/* no message to process, so perform next step 
of computation */ 
else 
ComputeNextPrimeNumber( ... );_ 


} 
while( !bDone ); 


Figure 1-8. 
The main message loop in a Windows program that yields control in the midst 
of a repetitive computation. Compare this with the message loop in Figure 1-4. 
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The Window Function 


In the sample application, TopLevelWndFn is the top-level window function, the 
function that processes all the messages that Windows sends to the application. 
TopLevelWndFn uses a switch statement to select from among four possible ac- 
tions. The most complicated action occurs in response to a WM_PAINT message: 
TopLevelWndFn calls the private function MsgPaint, which in turn calls 

-ShowModuleInfo to update the top-level window’s client area with information 
about the application’s module, task, and instance handles. 


The only other messages that ToplevelWndFn processes are WM _COMMAND 
and WM_DESTROY. In each case, TopLevelWndFn takes an action that causes 
another message to be sent to the application. Although at first glance this might 
appear redundant, it is actually a common programming strategy in Windows 
applications. Often the most efficient way to cause a particular action to be car- 
ried out is to send a message to a window function that initiates the action. 


For example, TopLevelWndFn processes WM_COMMAND by calling the private 
function MsgCommand, which checks whether the message’s wParam value is 
IDM_ENUM. If it is, MsgCommand calls InvalidateRect to generate a WM- 
_PAINT message in the application’s message queue. When TopLevelWndFn 
subsequently processes the WM_PAINT message, the top-level window’s client 
area is updated. In this way, the same function (MsgPaint) can be called in re- 
sponse to two different events: The window manager can send WM_PAINT 
whenever it determines that the client area needs to be repainted, or the user 
can generate WM_COMMAND with a wParam value of IDM_ENUM by choos- 
ing Enumerate from the application’s main menu. 


Similarly, TopLevel WndFn processes WM_DESTROY by calling the API function 
PostQuitMessage, which in turn places a WM_QUIT message in the application’s 
message queue. When GetMessage subsequently retrieves this message, it re- 
turns 0 and causes the application’s message processing to terminate. 


Of course, TopLevelWndFn receives many other messages that it does not pro- 
cess explicitly. For these messages, the default action is to pass them to Windows’ 
default message-processing function, Def WindowProc. 


What MODSTAT Does 


All the useful functionality of the sample application is encapsulated in two 
functions, ShowModuleInfo and WndEnumFn. ShowModuleInfo calls several 
Windows API functions to obtain information about the application module’s 
status. It uses the API functions wsprintf to format its output and TextOut to 
write to the top-level window’s client area. 
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ShowModuleInfo obtains information about other instances of the application by 
calling the API function EnumWindows. EnumWindows enumerates windows 
by calling WndEnumFn once for each overlapped and pop-up window in the 
window manager’s list. When WndEnumFn is called for the top-level window of 
an instance of MODSTAT, the corresponding task and instance handles are dis- 
played. The result is a display of the module’s name, handle, and reference 
count, and a list of the task and instance handles for each instance of the applica- 
tion, as shown in Figure 1-9. 


This is one of 4 currently executing tasks. 
Task handie: 11BD Instance handle: 1186 
Module handle: OE5D Name: MODSTAT Reference count = 3 


Other instances of this application 
Task handle: 0855 Instance handle: 11D6 
Task handle: 0795 Instance handle: 100E 


Figure 1-9. 

Three instances of the sample application MODSTAT. Two of the instances are 
iconic; the third displays the task and instance handles of all three instances of 
the application. 


The structure of a Windows application reflects the design of the Windows envi- 
ronment. Applications that interact harmoniously with the Windows environ- 
ment are the easiest to debug. The time you spend in careful structural design of 
your source code will be amply repaid in terms of the time you save in 
debugging. 
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2: DEBUGGING 


There is no secret way to debug a Windows program. You need the same combi- 
nation of prevention, perseverance, and intuition to debug in Windows as you 
need in any other programming environment. In the Windows environment, you 
have a variety of debugging techniques and tools at your disposal. Some of these 
are unique to Windows, whereas others are simply traditional programming 
techniques with a Windows twist. The key to efficient debugging, however, is 
not a technique at all—it is a well-designed program. 


e e e 
Designing for Debugging 

The principle that good software design leads to easier debugging holds true in 
Windows. In general, an easy-to-debug Windows program has a structure that 
reflects the way the program interacts with the Windows environment. For ex- 
ample, you may want to isolate different window functions in different units of 
source code so that the functionality of each window in a program is encapsu- 
lated in its own unit of source code. There are also a few specific details of 
source-code design that will help make your Windows programs easier to 
debug. These include simple source-code statements, modular design, and accu- 
rate use of functions and variables. 


Use Simple Source-Code Statements 


When you use one of the debuggers supplied with the Microsoft Windows SDK, 
the best you can do when you find a bug is to associate it with a particular line of 
source code. You can more easily pinpoint a bug if you use simple source-code 
statements and limit yourself to only one statement in each line of source code. 


Modularize Your Source Code 


Modular source code simplifies debugging. This is especially true in Windows, 
where initialization code, message dispatching loops, and window functions fall 
naturally into separate blocks of source code. Often the quickest way to zero in 
on a bug is to recognize which block of source code is malfunctioning. 


When you use one of Microsoft’s Windows debuggers—CodeView, SYMDEB, or 
WDEB386—you can benefit from keeping a program’s source code in separate 
files. If you use the medium memory model to compile your applications, the 
Microsoft C compiler will assign each source-code file’s name to the correspond- 
ing executable-code segment. When a debugger subsequently traps a bug, it 
uses the name of the segment and an offset into the segment to locate the bug in 
the executable code. You can then work backward from the segment name and 
offset to a particular line of source code in the corresponding file. 
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Use Function Prototypes 


Some of the toughest bugs to fix are those that occur when the C compiler makes 
invalid assumptions about the data types associated with the parameters in a 
function call. You can avoid this kind of error by incorporating function proto- 
types throughout your source-code design. For functions used only within a 
‘single source-code module, place your function prototypes near the beginning 
of the module, before you define any of the prototyped functions. For functions 
that are used globally, place function prototypes in an include file and include 
the file after WINDOWS.H in any source-code module that makes global calls. 


Avoid Static and Global Variables 


Another tough bug to uncover in a Windows application occurs when a window 
function stores data in a static or global variable. Typically, the value is some- 
thing that is used only within a particular window, such as a GDI handle or a 
pointer to a window function. 


The problem with using a static or global variable is that only one window at a 
time can store data in the variable. If two windows in your application store data 
in the same static or global variable, one window must lose its data. You can 
avoid this bug by storing window-specific data in a window's extra bytes or 
property list rather than in a static variable. (There is more information about 
window extra bytes and property lists in Chapter 5.) 


You should use a static or a global variable only if you are certain that only one 
window at a time will ever access the variable. Nevertheless, a safer technique is 
to reserve static and global variables for values that are truly global and not pri- 
vate to a particular window. 


Using a Debugging Terminal 


One way to save time when debugging a Windows application is to use a debug- 
ging terminal to display debugging data while the application executes. A 
debugging terminal consists of a dumb terminal (keyboard and screen) con- 
nected to your computer’s serial communications port through a null-modem 
cable. You can also use a second computer and a terminal-emulation program 
instead of a dumb terminal. If your computer system contains two different 
video subsystems, you can emulate a debugging terminal by using one video 
subsystem for Windows and the other for displaying debugging data. This 
method requires you to use a special device driver that redirects serial output to 
the second video subsystem. Such device drivers are in the public domain and 
can be downloaded from bulletin-board systems such as CompuServe. 
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The reason to use a debugging terminal is so that you need not rely on the Win- 
dows screen to view debugging data. If you try to debug entirely within the con- 
fines of the Windows display, you will find that your application can’t get out of 
its own way when it tries to display debugging information. The bug that crashes 
your application might prevent the application from displaying the debugging 
message that would help you identify the bug. 


You can make good use of a debugging terminal with the tools provided in 
the Windows SDK. The Windows API supports a function called Output- 
DebugString, which sends a string to the debugging terminal. Furthermore, 
when the debugging version of Windows traps an error that causes a fatal exit or 
when an application detects an error and calls the FatalExit API function, Win- 
dows displays the error number and a stack trace on the debugging terminal. 
Also, all three of Microsoft’s Windows debuggers support the use of a secondary 
monitor, a debugging terminal, or both. 


Windows Debuggers 


Three debuggers are supplied with the Windows SDK: CodeView for Windows, 
SYMDEB, and WDEB386. Although all three use a similar set of debugging com- 
mands, each gives you a different view of the Windows environment. The 
debugger you use for a particular application depends on your debugging needs. 


If you want to debug in protected mode, use CodeView or WDEB386. To debug 
in real mode, use SYMDEB. Use WDEB386 if you need access to descriptor 
tables, I/O ports, and other low-level components of the Windows environment. 
All three debuggers let you debug a program at the level of assembly language, 
but if you want to use a debugger that can display C source-code statements, you 
must use CodeView or SYMDEB. 


CodeView 


Of the three SDK debuggers, CodeView is probably the best suited to Windows 
application debugging. CodeView lets you view an application’s C source code, 
set breakpoints, and trace through the source code as the program executes. 
Also, CodeView is the only one of the three debuggers that lets you monitor the 
flow of window messages and set breakpoints on specific messages. Sometimes 
the quickest way to home in on a mysterious bug is to use CodeView’s wwm 
(Windows watch message) command on all of an application’s window func- 
tions to determine which message causes the bug to appear. 


31 


Windows: Developer’s Workshop 


Before you use CodeView, you must compile and link your application with spe- 
cial command-line switches, as shown in Figure 2-1. The /Od switch disables 
compiler optimization that could interfere with debugging. The /Zi and /CO 
switches cause line numbers and symbols (function and variable names) to be 
incorporated into the application’s executable file for CodeView’s use. This extra 
debugging information does not affect the flow of control of the application. 
CodeView uses the symbols and line numbers to associate names with their cor- 
responding memory locations and to display source-code statements as the pro- 
gram executes. 


Switch Program Comments 
/Od Microsoft C Compiler Disables all compile-time optimizations 
/Z1 Microsoft C Compiler Includes line-number, global-name, and 


local-name information in compiled code 


/CO Microsoft Linker Includes line-number, global-name, and 
local-name information in executable file 


Figure 2-1. 
Compiler and linker switches for preparing a program for debugging with 
CodeView. 


SYMDEB 


SYMDEB (a SYMbolic DEBugger) provides a superset of the functionality sup- 
ported in the MS-DOS debugger, DEBUG. Like DEBUG, SYMDEB lets you in- 
spect data in memory. It supports breakpoints at the assembly-language level 
and lets you view both assembly-language instructions and the corresponding 
C-language source-code lines. 


You need a debugging terminal to use SYMDEB. If your computer system con- 
tains two video subsystems, one of which is a monochrome display adapter, 
SYMDEB can use the monochrome screen as a debugging terminal. You start 
SYMDEB by running it on your primary display. To redirect output to a mono- 
chrome display, specify the /m switch on the SYMDEB command line. If you’re 
using a debugging terminal, redirect SYMDEB’s output to the debugging termi- 
nal with SYMDEB’s =COM1 or =COM2 command. You begin debugging by set- 
ting breakpoints and source-code display options. Then you let SYMDEB 
execute your Windows application. 


To prepare an application for debugging with SYMDEB, use the compiler and 
linker switches listed in Figure 2-2, and use the MAPSYM utility to create a SYM 
(symbol) file from the .MAP file for the application. 
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Switch Program Comments 

/Od Microsoft C Compiler Disables all compile-time optimizations 

/Za Microsoft C Compiler Includes line-number and global-name 
information in compiled code 

/MAP Microsoft Linker Creates .MAP file 

/LI - Microsoft Linker Includes line-number information in 
.MAP file 

Figure 2-2. 


Compiler and linker switches for preparing a program for debugging with 
SYMDEB or WDEB386. 


SYMDEB does not support a full-screen interface as CodeView does. Also, 
SYMDEB runs only in real mode, not in protected mode. Despite these draw- 
backs, there are certain debugging situations in which you might need SYMDEB. 
One is when you suspect that a bug in your application occurs as a result of Win- 
dows’ memory manager moving a block of global memory. Because the pointers 
used to access global-memory blocks can be invalidated only in real mode, 
SYMDEB is the best tool for finding such a bug. Also, if you suspect that a bug is 
related to an application’s use of expanded (EMS) memory, you can use SYMDEB 
to monitor expanded-memory activity as the application runs. 


WDEB386 


If you want to debug in protected mode, an alternative to using CodeView is to 
run WDEB386 with a debugging terminal. Despite its name, WDEB386 runs on 
both 80286 and 80386 CPUs. WDEB386 lacks the convenient features of 
CodeView, such as a full-screen interface and the ability to debug source code as 
well as assembly-language code. On the other hand, WDEB386 gives you access 
to elements of the programming environment that are not available through 
CodeView, including the contents of the global and local descriptor tables. This 
feature makes WDEB386 particularly useful to device-driver developers and to 
assembly-language programmers. 


You can also use WDEB386 to debug Windows applications that are written in C. 
Prepare an application for debugging with WDEB386 the same way you do for 
SYMDEB. Use the compiler and linker switches listed in Figure 2-2, and create a 
SYM file for the application by using MAPSYM. If your source code is contained 
in more than one C source file, you might also want to use the /AM switch with 
the Microsoft C compiler to build the application with the medium memory 
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model. This memory model may be easier to use when you work backward from 
an assembly-language instruction in WDEB386 to a line of source code in a C 
source file. You might also use the /Fc switch, which produces a .COD file that 
lists both source code and the corresponding compiler-generated assembly 
language. 


When you load WDEB386, the command-line options you use depend on the 
debugging environment. Use the /C: switch to specify which serial communica- 
tions port WDEB386 will use and the /S: switch to specify symbol files. With an 
80286-based computer, use KRNL286.SYM and the /% (standard mode) switch: 


WDEB386 /C:1 /S:krn1286.sym /S:myapp.sym win.com /s myapp 


In an 80386 environment, specify KRNL386.SYM and either the /s (standard 
mode) or the /3 (enhanced mode) switch: 


WDEB386 /C:1 /S:krn1386.sym /S:myapp.sym win.com /3 myapp 


Figure 2-3 illustrates how WDEB386 might be used to find a bug that has pro- 
duced an “Unrecoverable Application Error” message in an application called 
MYAPP. When WDEB386 starts, it lets the Windows kernel run long enough to 
establish the protected-mode environment. It then halts at a breakpoint (INT 3) 
that is built into the Windows kernel. This breakpoint exists only to return con- 
trol to the debugger so that you can set breakpoints in your application and ad- 
just WDEB386 display options. 


In Figure 2-3, three commands are entered at the # prompt after this breakpoint 
is encountered. The y 386env command toggles the 38G6env flag, which causes 
WDEB386 to display only the 16-bit CPU registers. The z command replaces the 
INT 3 breakpoint instruction with a NOP so that it won't be encountered again. 
Then the g command transfers control to the application. | 


When the application encounters the bug, the familiar “Unrecoverable Applica- 
tion Error” message box appears on the Windows screen. Selecting the Cancel 
button in the message box returns control to WDEB386, which displays the 
assembly-language instruction that caused the error. In Figure 2-3, the instruc- 
tion is MOV AL, BYTE PTR ES.[BX+SI/. Because the instruction accesses memory, 
it’s a good bet that the cause of the error is an attempt to access a protected 
memory location. The d/ es command, which displays the ES entry in the Local - 
Descriptor Table, verifies that this is the case. The selector in ES (05DH) is a 
valid data-segment selector because the d/ es command successfully displayed a 
descriptor-table entry. However, the largest valid offset in the segment (that is, 
the segment limit) is OOOFH. Because the offset [BX+SI] is 0010H, the error is that 
the program has attempted to read a byte that lies outside the data segment. 
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Microsoft (R) Windows 3.0 Kernel Debugger Version 2.75 09.Mar.90 


Copyright (C) Microsoft Corp 1990. All rights reserved. 


[80286] 

Map linked (KERNEL) 
Map linked (USER) 

Map linked (GDI) 

Map linked (MYAPP) 
DOSX! DATA (0000) =3ACF 
DOSX! CODE (0296) =3D65 
DOSX! CODE (04CF) =0050 
KERNEL! IGROUP=02D5 
KERNEL! _NRESTEXT=02DD 
KERNEL! MISCTEXT=02E5 
SYSTEM! CODE (0001) =036D 


MSDOS! CODE (0001) =0F45 
MSDOS ! CODE (0002) =0F4D 
MSDOS ! CODE (0003) =0F55 
MSDOS ! DATA (0006) =0F75 


AX=000042F0 Bx=0000138F Cx=00000000 Dx=00000006 SI=00000E08 DI=00000000 
IP=0000827E SP=00001A76 BP=00001A98 CR2=00000000 CR3=00000 IOPL=3 F=-- -- 
CS=02D5 SS=0F75 DS=0081 ES=0DF5 FS=0000 GS=0000 -- NV UP EI NG N2 NA PO NC 


02D5:0000827E INT 3 

#fy 386env 

#2 
02D5:827E INT 3 replaced with: NOP 
#g 

MYAPP! TEXT=06AD 

MYAPP ! DGROUP=069D 

MYAPP!MYAPP_TEXT=0E4D 


AX=0000 BX=0000 Cx=105D DX=105D SP=1514 BP=1524 SI=0010 DI=104E 


IP=036C CS=0E4D DS=069D ES=105D SS=069D -~ NV UP EI NG NZ AC PE CY 
OE4D:036C MOV AL, BYTE PTR ES: [BX+SI] ES:0010=INV: 0003 
#dl es 

105D Data Bas=04AB70 Lim=000F DPL=1 P RW A 

#1n 


0E4D:01D0 MYAPP!MYAPP_TEXT:WndFn + 19C 


Figure 2-3. 
A sample debugging session in WDEB380. 


You can find the bug in the C source code by using the location of the assembly- 
language instruction that caused the error. (In Figure 2-3, the segment:offset 
location of the instruction is 0E4D:036C.) The /n command shows that the code 
segment that contains the instruction is named MYAPP_TEXT. You can then 
refer to the list of line numbers in MYAPP.MAP that correspond to MYAPP_TEXT 
as shown in Figure 2-4. From this list you can see that the value of the offset, 


35 


Windows: Developer’s Workshop 


036CH, lies somewhere in the executable code that corresponds to line 323 of 
the source code. Finally, a look at line 323 in MYAPP.C in Figure 2-5 reveals the 
bug: The array subscript 7 is larger than the size of the global-memory block to 
which pData points. 


Line numbers for myapp.obj(myapp.c) segment MYAPP_TEXT 


62 0001 :0000 67 0001 :000D 68 0001:0020 69 0001:0024 

72 0001 :0026 74 0001 :003B 75 0001:0045 78 0001:004F 

79 0001:0066 89 0001:0070 90 0001:007A 91 0001 :0080 

93 0001:0089 95 0001 :0095 96 0001:00A1 107 0001:00A9 
112 0001:00B6 113 0001:00BE 114 0001:00C4 115 0001:00CE 
116 0001:00DD 117 0001:00EC 118 0001:00F4 119 0001:00F9 
120 0001:00FE 121 0001:0103 123 0001:0108 124 0001:0112 
135 0001:011A 136 0001:0124 137 0001:0131 154 0001:0139 
161 0001:0146 176 0001:014C 179 0001:0174 180 0001:017D 
181 0001:0188 183 0001:0193 184 0001:0199 187 0001:01A2 
188 0001:01AD 190 0001:01B5 192 0001:01C5 193 0001:01c8 
203 0001:01D0 204 0001:01DA 223 0001:01ED 207 0001:0203 
208 0001:0216 211 0001:0218 212 0001:0228 215 0001:022A 
216 0001:0232 219 0001:0234 227 0001:023B 228 0001:023E 
238 0001:0248 239 0001:0252 242 0001:0262 243 0001:026A 
246 0001:026C 247 0001:0274 250 0001:0276 256 0001:027F 
266 0001:0287 267 0001:0291 277 0001:0299 281 0001:02A6 
282 0001:02BB 283 0001:02CD 284 0001:02D8 294 0001:02E0 
300 0001:02ED 302 0001:02FD 303 0001:0306 305 0001:030F 
307 0001:0321 308 0001:032E 313 0001:0336 319 0001:0344 
320 0001:0352 322 0001:035E 323 0001:0366 325 0001:037C 
326 0001:0384 328 0001:038C 329 0001:038F 


Figure 2-4. 

Line numbers and offsets in a .MAP file produced by MAPSYM. If you know a 
segment name and offset, you can use this table to find the corresponding 
source-code line number. 


Line 


312. static int Bomb( HWND hWnd ) 


313° { 
314 LPSTR pData; 
315 GLOBALHANDLE hData; 
316 int i,n; 
Figure 2-5. | (continued) 


An excerpt from source code that contains a memory-protection bug. 
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Figure 2-5. continued 


317 

318 

319 hData = GlobalAlloc( GHND, 16L ); 
320 pData = GlobalLock( hData ); 

321 

322 for( n=0; n<20; nt+ ) 

323 i += pData[n]; 

324 


325 GlobalUnlock( hData ); 
326 GlobalFree( hData ); 
327 

328 return i; 

329} 


Useful Debugging Tecimiques 
Along with the assortment of debugging methods provided by Windows debug- 
gers, there are several programming techniques that you can use to prevent and 
detect errors in your Windows applications. You should choose the debugging 
techniques best suited to the kind of bug you are hunting and to your personal 
debugging style. 


Using the Debugging Version of Windows 


The foremost rule of thumb in debugging a Windows application is this: Always 
use the debugging version of Windows to test your application. The debugging 
version notifies you of errors that might pass undetected in the retail Windows 
version. For example, if an application calls LocalFree to free a block of memory 
that has been locked (by calling LocalLock) but not unlocked (by calling 
LocalUnlock), the debugging version of Windows interrupts the application with 
an error message and a prompt to abort (terminate the application), ignore (con- 
tinue execution despite the error), or break (give control to the debugger). If you 
used the retail version of Windows, this error would pass unnoticed. 


Scaffolding is a time-honored debugging technique that consists of embedding 
extra debugging source code in a program. The purpose of scaffolding is to track 
the state of the program at key locations in the source code. Here are some of the 
many ways to use scaffolding: 


a To view the intermediate results of computations. 


& To monitor variables whose values control what is drawn on the screen. 
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m To record a program’s flow of control. 


m To test sections of source code that might otherwise execute only 
occasionally. 


The most effective way to incorporate scaffolding into an application is to com- 
pile it conditionally. For example, Figure 2-6 contains code that calls Output- 
DebugString to display the values of the hWnd, hData, and pData variables. The 
#ifdef and #endif preprocessor directives bracket the scaffolding code so that it 
is compiled into the application only if the symbol DEBUG is defined at compile 
time. (You can use either a #define directive in the source code or the /D switch 
on the Microsoft C compiler’s command line to define the symbol DEBUG.) This 
technique lets you include or omit debugging code, without modifying the ac- 
tual source code, by recompiling with or without the appropriate preprocessor 
symbol definitions. You can use this technique to create levels of debugging 
code that provide different amounts of debugging output by nesting condi- 
tionally compiled code using two or more preprocessor symbols. 


void TestFn( HWND hWnd, GLOBALHANDLE hData ) 


{ 
LPSTR pData; 


#ifdef DEBUG 
char DebugString [64]; 


wsprintf( DebugString, "TestFn: er nae hData=%04X, pData=$081x\r\n", 
hWnd, hData, pData ); 
OutputDebugString( DebugString ); 
#endif 


pData = GlobalLock( hData ); 
MessageBox( hWnd, pData, "Test", MB OK ); 
GlobalUnlock( hData ); 

} 


Figure 2-6. 
Conditionally compiled scaffolding (debugging code) in a Windows function. 


Scaffolding techniques complement the use of a debugger to single-step through 
source code and to set breakpoints or watchpoints. The Windows API function 
OutputDebugString is designed to be used with a debugger as well as with a 
debugging terminal. If you’re using CodeView, for example, OutputDebugString 
directs its output to CodeView’s command window. 
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Tracing Messages 


Because flow of control in a Windows program is governed by messages, one of 
the most productive ways to debug a Windows application is to trace the flow of 
messages. If a bug appears in response to a particular message, a good place to 
look for the error is in the source code that processes the message. 


There are at least three ways to trace messages. The easiest is to use the Spy 
utility in the Windows SDK, which lets you use the mouse to select a window 
and then shows you the window’s messages as they are processed. However, Spy 
can spy only on visible windows. You can’t use Spy to trace a window’s messages 
if the window isn’t visible somewhere on the screen. 


A more selective approach is to use CodeView, which lets you debug your appli- 
cation as well as trace messages. CodeView’s wwm (Windows watch message) 
command lets you trace specified messages in multiple window functions as 
well as in multiple instances of the same window. Figure 2-7 shows how 
CodeView displays the first few messages sent to the top-level window of an 
application. 


HWND:1340 wParam:0000 1Param:0C8D07C4 msg:0024 WM_GETMINMAXINFO 
HWND:1340 wParam:0000 1Param:12351524 msg:0081 WM_NCCREATE 
HWND:1340 wParam:0000 1Param:1235150A msg:0083 WM_NCCALCSIZE 
HWND:1340 wParam:0000 1Param:12351524 msg:0001 WM_CREATE 
HWND:1340 wParam:0001 1Param:00000000 msg:0018 WM_SHOWWINDOW 


Figure 2-7. 
Sample message trace produced by using CodeView’s wwm command. 


CodeView’s message-tracing ability is particularly useful when you combine it 
with the whm (Windows break message) command, which lets you set a break- 
point on a particular message. One way to locate a bug in a Windows program is 
to use wwm to trace messages until the bug appears. If the bug seems to be 
associated with a particular message, you can use whm to set a breakpoint on 
the message and then single-step through the code that processes the message. 


A third message-tracing technique is to embed message-decoding scaffolding in 
an application’s window functions. One way to do this is to write a function that 
uses a switch statement to decode a message’s wMsg, wParam, and lParam pa- 
rameters. The function should use OutputDebugString to display the message 
contents. This technique lets you trace specific messages and parameters more 
informatively than you can with CodeView or Spy. 
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intercepting API Functions 


A clean way to encapsulate debugging code is to construct a set of functions that 
intercept calls to Windows API functions. Each intercept function can surround a 
Windows API call with error checking and other scaffolding. 


Figure 2-8 shows how you might design a set of intercept functions for the Win- 
dows API functions that access window extra bytes. The four functions xGWW, 
xSWW, xGWL, and xSWL intercept calls to the GetWindowWord, SetWindow- 
Word, GetWindowLong, and SetWindowLong Windows API functions. The func- 
tions trap any attempts to access or set window extra bytes that are not allocated 
for the specified window. 


static char szMsg[80]; 
static char szOOB[]. = " out of bounds\r\n"; 


[REFERRER EEE EE SERRE THOR EERO EERE RHE REE ORE REE EEE EEE SHE NEE ROHR EEE E EERE EE EE EH ERED 


* * 
* xGWW--Intercepts GetWindowWord * 
* * 


SHORE EF EERE THOR ETE ERE E TENET EERE OEP E SOE EESEDHEEH HEPES ETERS TRH ER ETRE EERE EERE EH / 


WORD PASCAL FAR xGWW( HWND hWnd, int nOffset ) 


{ 
WORD’ = wRVal; 


if( IsOK( hWnd, nOffset, sizeof(WORD) ) ) 
wRVal = GetWindowWord( hWnd, nOffset ); 


else 


{ 
MessageBeep( 0 ); 
wsprintf(. szMsg, "GetWindowWord( %04X, %d)", hWnd, nOffset ); 
lstrcat ( szMsg, szO0OB ); 
OutputDebugString( szMsg ); 


wRVal = 0; 
} 


return wRVal; 


Figure 2-8. (continued) 
Intercept functions for debugging calls to GetWindowWord, SetWindowWord, 
GetWindowLong, and SetWindowLong. 
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Figure 2-8. continued 


[RARER EEE EERE EEE E EE EEE ETRE EEE EERE TEETER ETHER EERE RENEE ER EEE 


* * 


* xSWW--Intercepts SetWindowWord : 


* * 


HEHEHE THEE ETHER EHH EEE EEE TEER EERE E REET ETE E REESE EER HER HERR E RR ERE Te / 


WORD PASCAL FAR xSWW( HWND hWnd, int nOffset, WORD wNew ) 


{ 
WORD wRVal; 


if( IsOK( hWnd, nOffset, sizeof(WORD) ) ) 
wRVal = SetWindowWord( hWnd, nOffset, wNew ); 


else 
{ 
MessageBeep( 0 ); : 
wsprintf( szMsg, "SetWindowWord( %04X, %d, %u )", 
hWnd, nOffset, wNew ); 
istrceat( szMsg, szOOB ); 
OutputDebugString( szMsg ); 


wRVal = 0; 
} 
return wRVal; 


} 


| hk heheheh tekehehetateteteheletateheahatetakehetshetketotlahelteheheheleteh tehehtekeh telehehteh kheleh keh hdehedk khehetelek teleheht the 


* * 


* xGWL--Intercepts GetWindowLong * 


* * 


HORE RE HEE E EEE E EEA EE EERE TEER EEE RER TEER ER EEE HEE EE ETE TE REET E RE RRR EE RHE EEE EH / 


LONG PASCAL FAR xGWL( HWND hWnd, int nOffset ) 


{ 
LONG  1RVal; 


if( IsOK( hWnd, nOffset, sizeof(LONG) ) ) 
1RVal = GetWindowLong( hWnd, nOffset ); 


else 


{ 
MessageBeep( 0 ); 
wsprintf( szMsg, "GetWindowLong( %04X, %d )", hWnd, nOffset ); 
lstrceat( szMsg, szOOB ); 
OutputDebugString( szMsg ); 


1RVal = OL; 


(continued) 
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Figure 2-8. continued 


return 1RVal; 


[ARR RER EERE REE EERE EERE EERE ERE EEE EERE THERE REET EERE EERE EHH R REO H HEE HH EEE 
+ * 
* xSWL--Intercepts SetWindowLong * 
* * 


FEEHEH ERE R EEN E EEE O EHS H EEE EERE ESSE HERE E EEE E HERE HEE RET HERR SERRE HEE HE / 


LONG PASCAL FAR xSWL( HWND hWnd, int nOffset, LONG 1New ) 


{ 
LONG 1RVal; 
if( IsOK( hWnd, nOffset, sizeof(LONG) ) ) 
1RVal = SetWindowLong( hWnd, nOffset, 1New ); 
else 
{ 
MessageBeep( 0 ); 
wsprintf ( 8zMsg, "SetWindowLong( %04X,. $d, %lu )", 
hWnd, nOffset, l1New ); 
istrcat( szMsg, szOOB ); 
OutputDebugString( szMsg ); 
1RVal = OL; 
} 
return 1RVal; 
} 
[PERERA EERE E EERE EERE EEE E RE EEO EERE REE EEE E RHEE EERE EERE EEE EERE HERE RHEE EEE HD 
* * 
* IsOK--Tests whether specified space is allocated * 
* * 


CREE EEE EERE EEE EER EE ERE E ERE EERE EEE E PEER EERE TREE RHEE EERE EERE RHR ERROR RHEE | 


static BOOL IsOK( HWND hWnd, int nOffset, int nSize ) 
{ 

int nEB; 

BOOL .. bRVal = FALSE; 


if( nOffset >= 0 ) 

{ 
nEB = GetClassWord( hWnd, GCW_CBWNDEXTRA ); 
bRVal = (nOffset + nSize) <= nEB; 


} 
return bRVal; 
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Although you can incorporate intercept functions directly into a program’s 
source code, a more flexible strategy is to build intercept functions into a 
dynamic link library. (Chapter 3 contains more information on dynamic link li- 
braries.) In the library’s module-definition (.DEF) file, assign each intercept func- 
tion an export name that matches the name of the corresponding API function, 
as shown in Figure 2-9. 


EXPORTS WEP @1 RESIDENTNAME 
GetWindowWord = xGWW @133 
SetWindowWord = xSWW @134 
GetWindowLong = xGWL @135 
SetWindowLong = xSWL @136 

Figure 2-9. 


Exporting intercept functions in the module-definition file of a dynamic link 
library. The exported names are identical to the corresponding functions in the 
Windows API. 


After you compile the dynamic link library, use IMPLIB to create an import li- 
brary for the intercept functions. You can then debug an application by linking 
the application with the DLL’s import library before the standard Windows API 
library (LIBW.LIB): ) 


LINK /NOD /NOE myapp, , , intercpt libw, myapp 


Placing the reference to the import library (in this example, INTERCPT.LIB) 
ahead of the reference to LIBW.LIB causes the application's API calls to be linked 
to the intercept functions in INTERCPT-.DLL instead of the default Windows API 
functions. However, the intercept functions themselves will be linked to the 
default API functions. When you execute the application, the intercept functions 
will be called. When you finish debugging, you can simply recompile the appli- 
cation without reference to INTERCPT.LIB, so all the application’s API calls will 
be linked directly to the default Windows functions. 


Common Bugs 
The most commonly encountered bugs in Windows applications are related to 
the nature of the Windows environment. Windows applications run in a visually 
rich, interactive system where programming errors quickly become visible on 
the screen. Also, Windows’ memory-management strategy, in which blocks of 
memory are managed dynamically outside the control of an application, can un- 
mask a number of subtle programming errors. 
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Visible Bugs 

It is usually easy to find bugs that affect the appearance of a window. If you 
create a window with the wrong style or initialize the window’s background 
color with the wrong value, the visual appearance of the window will clue you in 
to the problem in your source code. If your list-box controls don’t list or your 
scroll-bar controls don’t scroll, a good place to look for a bug is in the source 
code responsible for manipulating and responding to those controls. 


A trickier bug to discover is one that causes a window never to appear on the 
screen at all. Here are several reasons why this may happen: 


m The window function is not exported. 


m An invalid window class name or instance handle is specified in the 
WNDCLASS data structure when RegisterClass is called. 


m The window class name or parent-window handle specified in the Create- 
Window function is invalid. 


m The window function does not pass unprocessed messages to another win- 
dow function such as DefWindowProc. 


m The window does not have the WS_VISIBLE style, or calls to ShowWindow 
or UpdateWindow do not execute successfully. 


m@ The window is overlapped by another window. 


@ The window has no border, and its class background color is the same as 
the desktop (COLOR-BACKGROUND) or the parent’s client area 
(COLOR_WINDOW). 


You can avoid some of these problems by checking the return values from func- 
tions such as RegisterClass and CreateWindow. In other cases, the only way to 
find the bug is to use a debugger or appropriate scaffolding to examine the 
WNDCLASS data structure, window handle, and window style bits. 


Confusing Static and Automatic Data 


Another type of bug is related to the notion of static and automatic data elements 
in the C programming language. Storage space for static data elements is allo- 
cated in a program’s default data segment. Thus the space reserved for static data 
remains allocated as long as your program executes. In contrast, memory for au- 
tomatic data elements is allocated on the stack at the time control is transferred 
to the function in which the automatic variables are declared. When the function 
exits, the stack memory is reclaimed, and the values of the automatic data ele- 
ments are lost. 
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This kind of bug can appear in a window function if the function stores a value 
in an automatic variable in response to a message and then attempts to use that 
value in response to a subsequent message. In Figure 2-10, for example, Brush 
is declared as an automatic variable. Because memory for bBrush remains allo- 
cated only until WndFn returns, the value stored in bBrush when the message 
WM_CREATE is processed is no longer available when WM_CTLCOLOR is pro- 
cessed. The bug can be fixed by declaring bBrush as a static variable or by stor- 
ing the brush handle in the window’s extra bytes or property list. 


LONG PASCAL FAR 
WndFn( HWND hWnd, WORD wMsg, WORD wParam, LONG 1Param ) 


{ 
HBRUSH hBrush; /* hBrush is an automatic variable */ 


switch( wMsg ) 


{ 
case WM_CREATE: 
hBrush = GetStockObject ( GRAY_BRUSH ); 
break; 


case WM_CTLCOLOR: 
return MAKELONG( hBrush, 0 ); /* ERROR: hBrush isn't valid */ 
break; 


Figure 2-10. 
A bug caused by using an automatic variable (hBrush) to store a value across 
multiple messages. 


The debugging version of Windows is designed to catch a variety of common 
bugs. When a bug occurs, the debugging version displays an error number that 
indicates the nature of the error. Appendix C of the reference manual in the Win- 
dows SDK documentation contains a complete list of fatal-exit error codes. 


Following the error number, the debugging kernel produces a stack trace that 
lists the return addresses for the function calls that occurred prior to the error. 
This information appears on the debugging terminal unless you’re using 
CodeView, which displays it in the command window. 


Figure 2-11 on the following page shows a typical fatal-exit stack trace caused by 
an application’s attempt to use an invalid value for a global-memory handle. The 
topmost return address is the most recent. This list of addresses may seem cryp- 
tic, but if you use one of the Windows debuggers, you can work backward 
through the stack trace to the location in your source code that caused the error. 
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gdref: 


invalid handle 0000:3302 


FatalExit code = 0x0280 
Stack trace: 


02D5: 
21F56 
12A5: 
12A5: 
12A5: 
OBBS: 
12A5: 
12B5: 


02D5 


7BBA 


0352 
0278 
020E 
1005 
0032 
0077 


Abort, Break or Ignore? 


Figure 2-11. 
A stack trace displayed in CodeView’s command window by the Windows 
debugging kernel when a fatal error is detected. The error number (0x0280) 
indicates that the error resulted from an attempt to use an invalid global- 
memory handle. The return addresses on the stack are in selector:offset form. 


For example, you can use the v (view) command in CodeView to work back- 
ward from a return address in the stack trace to the source-code line where the 
error occurred. In the stack trace shown in Figure 2-11, the first two addresses in 
the list correspond to function calls made outside the application. (Entering 
v 0x02d5:0x7bba or v 0x02d5:0x1f56 in the command window produces the 
message “No source lines at this address.”) The next return address, however, 
does point within the application. Entering v 0x12a5:0x0352 moves the cursor 
to an assembly-language instruction that corresponds to line 320 of the applica- 
tion’s C source code, as shown in Figure 2-12. This is where the fatal error oc- 
curred. The bug occurs because the automatic variable bData was never 


initialized, as it probably should have been in line 319. 


318: 
319: 


12A5: 
12A5: 
12A5: 
12A5: 


320: 


12A5: 
12A5: 
12A5: 
12A5: 


0344 
0346 
0348 
034A 


034F 
0352 
0357 
035A 


Figure 2-12. 
A view of the combined source/assembly listing in CodeView’s source window, 
showing where the fatal error in Figure 2-11 occurred. 
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GlobalAlloc( GHND, 


16L ); 
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00 

10 
02D5 : 06E2 


Word Ptr [BP-04] 
02D5:09A0 
Word Ptr [BP-0A] , AX 


6A42 PUSH 
6A00 PUSH 
6A10 PUSH 
9AE206D502 CALL 
pData = GlobalLock( hData ); 
FF76FC PUSH 
9AA009D502 CALL 
8946F6 MOV 
8956F8 MOV 


Word Ptr [BP-08],Dx 
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Wild Pointers 


A wild pointer is a pointer to data in the wrong part of memory. When your pro- 
gram uses a wild pointer to read from or write to a memory location, almost 
anything can happen. If a wild pointer causes data in a program’s default data 
segment to be corrupted, you might be able to locate the source of the corrupted 
data very quickly. On the other hand, if a wild pointer points to a block of data 
owned by Windows itself, the program that crashes as a result of the corrupted 
data may not be the same as the one that contains the wild pointer. In such cases, 
a Wild-pointer hunt may seem more like a wild-goose chase. 


The reason wild pointers can be hard to isolate is that their bad effects often 
become apparent in misleading ways. As the result of a wild pointer, an applica- 
tion might terminate suddenly with only Windows’ “Unrecoverable Application 
Error” message box to indicate that something went wrong. A wild pointer can 
also crash a program in a confusing way, by causing a spurious fatal-exit error 
such as “invalid window handle” (error code 0x0007) or “gdref: invalid handle” 
(error code 0x0280). Such errors don’t represent what they seem to. They occur 
because your application has somehow clobbered data that actually belongs to 
Windows’ window manager or memory manager. If you see a fatal-exit error that 
seems unrelated to what a program is supposed to be doing, you can suspect a 
wild pointer. 


Most wild pointers are the result of “dumb” mistakes, unrelated to errors in pro- 
gram design or execution logic. Wild pointers can creep into a Windows applica- 
tion when you forget to initialize a pointer variable, make an error in pointer 
arithmetic, use a pointer to a memory block that has moved to another location, 
or fail to properly associate an exported function with its default data segment. 


Uninitialized pointer variables 
If you dereference a pointer without first specifying its value, you are almost cer- 
tainly accessing the wrong part of memory. This is an easy mistake to make 
when you program in C because the C language lets you use the same syntax to 
dereference both pointer variables and array names. Consider the following 
example: 

void UninitializedPointer () 

{ 

LPSTR Buf; 


Buf[0] = 0; /* ERROR: Buf is uninitialized! +*/ 
} : 
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In this function, the assignment statement contains a bug because the pointer 
Buf is uninitialized. The programmer’s intention might have been to declare Buf 
not as an LPSTR but as a character array: 


char Buf [50]; 


This kind of wild pointer is usually easy to trap when you debug in protected 
mode. There is only a small chance that the value that happens to be stored in an 
uninitialized pointer variable is actually a valid selector:offset combination, so 
CPU memory protection usually traps the error. When the error occurs, you'll 
see the “Unrecoverable Application Error” message box. With a debugger, you 
can view the assembly-language instruction that used the wild-pointer value. 


Errors in pointer arithmetic 

Another kind of wild pointer results from an error in pointer arithmetic. For ex- 
ample, the following loop addresses elements in an array that are not allocated in 
the array declaration: . 


int n, x[100]; 


for( n= 0; n < 200; n++ ) 
x[n] =n; 


Unfortunately, there is no way to check for pointer-arithmetic errors automati- 
cally during a program's execution. Your best bet is to debug in protected mode 
and hope that CPU memory-protection traps any errors in pointer arithmetic. 


When they don’t cause memory-protection errors, pointer-arithmetic bugs gen- 
erally lead to clobbered data. The way these bugs appear depends on the data 
you clobber. On the stack, you might overwrite a return address, which would 
cause a program to fail as soon as it tried to use the return address to return from 
a function call. You might also destroy the stack-frame pointer saved on the 
‘stack each time a function is called. This could lead to fatal-exit error 0x0303 
(‘invalid BP chain”). In the local heap, you might overwrite one of the linked-list 
pointers Windows memory manager uses to maintain the local heap. In this case, 
you might see fatal-exit errors 0x0100, 0x0103, or 0x0140, all of which occur 
when memory management of the local heap is disrupted. 
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Another way in which you might accidentally overwrite data is in calls to the API 
functions SetWindowWord and SetWindowLong, which are used to access win- 
dow extra bytes. You are certain to have problems if you specify the wrong byte 
offset or if you use SetWindowLong when you should have used SetWindow- 
Word. You will also corrupt data if you do not specify a large enough value for 
the cbWndExtra field of the WNDCLASS data structure when you register a 
window class. 


This kind of bug can cause an application to fail ina misleading way because the 
data being overwritten is used by Windows’ window manager. For example, you 
might see fatal-exit 0x0007 (‘invalid window handle”) or even 0x0140 (‘Local 
heap is busy”), when the real problem is that you used a window’s extra bytes 
incorrectly. You can also crash other applications by attempting to store data in 
window extra bytes beyond what you allocate in the WNDCLASS data structure. 
This happens because window extra bytes are part of a data structure in a heap 
maintained by Windows’ window manager on behalf of all windows in all appli- 
cations. If a program stores data beyond the allocated number of window extra 
bytes, it may corrupt the heap and disrupt all window management. 


Dissociated data segments 

In Windows, every instance of every application is associated with a different 
default data segment. Whenever control transfers to an application instance— 
that is, whenever an exported far function is called —Windows loads the CPU’s 
DS register with the segment value (in real mode) or selector (in protected 
mode) that identifies the instance’s default data segment. If this doesn’t happen, 
all sorts of wild-pointer errors can occur because the value in DS may not point 
to the default data segment associated with the instance. 


To understand why this is so, consider how Windows stores the appropriate 
default data-segment value in DS. In Windows programs, a short prolog of exe- 
cutable code precedes every exported far function in a module. Unless you pro- 
gram in assembly language, far-function prologs are generated by your high- 
level language compiler. For example, the Microsoft C compiler generates a 
prolog for every far function you compile using the /Gw command-line switch. 


The function prolog copies a data-segment value from register AX to DS, as 
shown in Figure 2-13. The correct data-segment value must be placed in AX by 
the function’s caller before it transfers control to the function prolog. 
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nop 
nop 

nop 

inc bp ; save BP+1 on stack 

push bp 

mov bp,sp ; save current stack pointer in BP 
push ds ; save current DS 

mov ds,ax ; copy AX to DS 


Figure 2-13. 
Exported far-function prolog in a Windows application. 


The data-segment value in AX is placed there in an instance thunk, a short piece 
of executable code that is created by calling the Windows API function 
MakeProcinstance. As shown in Figure 2-14, an instance thunk does nothing but 
store a data-segment value in AX and jump to the far-function prolog. By using a 
different instance thunk for each exported function in every application in- 
stance, Windows associates the correct default data segment with every far func- 
tion without needing multiple copies of each function's executable code. 


MOV ax, XXXX ; store the data-segment value in AX 
jmp FAR PTR function ; jump to exported FAR function 
Figure 2-14. 


An instance thunk. This piece of executable code is created by MakeProc- 
Instance. The instance thunk stores a data-segment value in register AX and 
jumps to the exported-function prolog shown in Figure 2-13. 


There are two ways in which you can disrupt this neat arrangement. One is sim- 
ply to forget to export a far function that should have been exported. In this case, 
the should-have-been-exported function uses the calling function’s default data 
segment instead of its own. This oversight causes problems as soon as the called 
function tries to access its static data or variables. 


Suspect this bug whenever a program’s static data seems to vanish. For example, 
the Microsoft C compiler stores string constants in a program’s default data seg- 
ment. Therefore, if you forget to export a function, all of the function’s far point- 
ers to the default data segment will be invalid. When this happens, string 
constants used as far-function parameters will seem to disappear. Consider the 
following C statement: | 


MessageBox( hWnd, "Hello, world", "This is a test", MB_OK ); 
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The MessageBox function uses far string pointers (LPSTR) as parameters. If the 
function containing MessageBox should have been exported but was not, both of 
the string parameters will be invalid, and MessageBox will fail to display the 
proper text. 


Another way that you might lose a function’s data segment is if you forget to call 
MakeProcinstance to create an instance thunk for a properly exported far func- 
tion. It is easy to forget to do this because you need not call MakeProcInstance 
for every exported far function. In particular, Windows itself creates an instance 
thunk when you call RegisterClass for an exported far function you use as a win- 
dow function. However, you must call MakeProcInstance for all other exported 
far functions in an application. If you don’t create an instance thunk for an ex- 
ported far function that needs one, the data-segment value used by the function 
may not be valid. In that case, any references to data stored in the default data 
segment will be invalid. Because there is no way for a debugger to tell you that 
you should have created an instance thunk, consider whether you need to use 
MakeProciInstance whenever you suspect a dissociated data segment in an ex- 
ported far function. 


Invalid far pointers to moveable data 

Some of the subtlest wild-pointer errors occur as a consequence of the normal 
operation of Windows’ memory manager. As the memory manager allocates a 
new block of memory in the global heap or enlarges an existing memory block, 
it can rearrange the global heap by relocating other moveable blocks of global 
memory. This is normally not a problem in protected mode (standard or en- 
hanced modes), but it can unmask wild pointers in real-mode applications. 


The reason lies in the way a block of global memory is addressed in the different 
CPU modes. In standard and enhanced modes, a global-memory address is a 32- 
bit value that consists of a 16-bit selector and a 16-bit offset. The selector desig- 
nates an entry in an 80286, 80386, or 80486 descriptor table. Part of each entry in 
the descriptor table is the address of the start of the memory block, which can lie 
anywhere in the CPU’s address space. When Windows’ memory manager moves 
a block of memory, it updates the block’s starting address in the corresponding 
descriptor table. This means that the 32-bit selector:offset address you use in a 
Windows application remains unchanged, even if the memory manager moves a 
memory block to a different location in physical memory. 


In real mode, however, there are no descriptor tables. A global-memory address 
consists of a 16-bit segment and a 16-bit offset. The segment value corresponds 
directly to a physical location in memory. If Windows’ memory manager moves a 
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block of memory, the block’s global-memory address contains a different seg- 
ment value. Consequently, if an application stores a global-memory address in a 
pointer variable, the address will be invalidated if Windows’ memory manager 
moves the global-memory block referenced by the pointer. 


The reason this kind of bug is hard to find is that you cannot always control or 
determine when the memory manager will move a particular block of memory. 
The pointer may remain valid for a long time before the memory manager relo- 
cates the memory block to which it points. Moreover, when the memory man- 
ager moves a block of memory, it does not necessarily store new data at the 
block’s previous address. This means that a wild pointer can continue to point to 
reasonable data even though it’s pointing to the wrong location in memory. 


The way to start looking for this kind of bug is to scrutinize your application’s use 
of far pointers. Suspect any far pointers to data in the application’s default data 
segment. Look carefully at the way the application accesses data in memory 
blocks allocated dynamically by GlobalAlloc. 


What you are looking for is a far pointer that is used after any function call that 
might cause the global heap to be rearranged. Because it can be very hard to de- 
cide whether a given function call can lead to global-memory movement, the 
best way to ensure that a far pointer remains valid is to ensure that the pointer 
references a block with a fixed location in memory. 


If the memory block is allocated by a call to GlobalAlloc that doesn’t specify 
GMEM_FIXED in its first parameter, be sure that far pointers to the block are 
used only between a pair of calls to GlobalLock and GlobalUnlock, as shown in 
Figure 2-15. The call to GlobalUnlock should be close enough to the GlobalLock 
call that you can easily see them as a pair in your source code. Don’t worry if you 
end up including a few extra calls to GlobalLock and GlobalUniock. Eliminating 
the possibility of a wild pointer is well worth the minuscule overhead involved 
in locking and unlocking the memory block. 


In real mode, Windows can also move the global-memory block that contains an 
application’s default data segment. If you are chasing a wild pointer in a real- 
mode application, look for far pointers to data in the default data segment. You 
can avoid this kind of problem by using near pointers instead of far pointers to 
data in the default data segment and stack. Figures 2-16 and 2-17 illustrate the 
wrong and right ways to point to data in the default data segment. 
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BYTE GetOneByte( GLOBALHANDLE hData ) 


{ 
LPSTR lpData; 


/* lpData contains a valid far pointer */ 
lpData = GlobalLock( hData ); 


/* (use lpData here) */ 


GlobalUnlock( hData ); /* 1lpData is no longer trustworthy */ 


/* if global memory is moved here, lpData might be invalid */ 


return *lpData; 


} 


Figure 2-15. 

This function is supposed to return the first byte of data in a moveable global- 
memory block. However, if the block moves after the call to GlobalUnlock, the 
Jar pointer \pData might become a wild pointer. 


void Create50EditWindows ( HWND hWnd, LPSTR szText ) 
{ 


int i; 
for( i = 0; i < 50; it+ ) 
CreateWindow( "Edit", szText, ... ); 


} 


Figure 2-16. 

The wrong way to point to a data item in an application’s default data segment 
is to place a far pointer in a variable or in a function parameter. Here, one of 
the calls to CreateWindow might cause Windows’ memory manager to increase 
the size of the default data segment to accommodate the edit-control text. In 
real mode, the default data segment could move and invalidate szText. 


void Create50EditWindows( HWND hWnd, NPSTR szText ) 
{ 


int i 
for( i = 0; i < 50; it+ ) 
CreateWindow( "Edit", szText, ... ); 


} 


Figure 2-17. 

The right way to point to the data item is to use a near pointer. CreateWindow 
requires a far pointer, so the C compiler generates code that converts szText 
into a far pointer dynamically each time CreateWindow is called. 
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The function Create50EditWindows is called with the address of a buffer, 
szText, that is located in the default data segment. The only difference between 
the two versions of Create5OEditWindows is the way the parameter szText is 
passed. In Figure 2-16, szText is a far pointer that can become invalid after 
CreateWindow executes. In Figure 2-17, szText is a near pointer that is converted 
to a far pointer dynamically each time CreateWindow is called. 


When you suspect a wild pointer to a moveable memory block, try using fixed 
global-memory blocks instead of moveable blocks. Use GMEM_FIXED instead 
of GMEM_MOVEABLE as a parameter to GlobalAlloc, and use FIXED instead of 
MOVEABLE in your module-definition (DEF) file to specify fixed segments. If 
the bug disappears, you’re probably on the right track. In particular, if the bug 
disappears only when you fix a particular block of memory, look carefully at 
pointers to data in that memory block. 


Trapping a wild pointer 

If you think you have a wild pointer and you don’t see a problem in your source 
code or module-definition file, you must trap the wild pointer by analyzing its 
bad effects. With luck, the wild pointer will point to the middle of a buffer whose 
contents you can examine. If you can identify the data inadvertently stored in the 
buffer when the wild pointer was used, you should be able to find the wild 
pointer in your source code. 


When you can’t find the wrongly stored data, you should take a more systematic 
approach. Start by running the application in protected mode (standard or en- 
hanced mode). In protected mode, any of the following wild-pointer errors will 
lead to an “Unrecoverable Application Error” message: 


m An attempt to store data in an executable-code segment. 


m An attempt to use a far pointer with an invalid selector (such as might occur 
with an unitialized or null pointer). 


m An attempt to read or write beyond the extent of a block of memory—that 
is, with a pointer whose selector is valid but whose offset points outside of 
the allocated size of the block. 


These errors are normally trapped by the memory-protection feature of the 
80286, 80386, and 80486 processors. To locate the pointer that causes one of 
these errors, run your application under CodeView in the debugging version of 
Windows. CodeView will trap the error and display this message: 


Trap 13 (ODH) - General Protection Fault 
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Then CodeView will highlight the location in your application where the wild 
pointer is used. 


Unfortunately, Windows version 3 does not make use of CPU memory protection 
to insulate an application’s data segments from wild pointers in other applica- 
tions. This means that a wild pointer in an application can cause corrupted data 
in a different application or even within Windows itself. If you suspect this kind 
of problem, the next step is to try to unmask the wild pointer by causing it to 
point to a protected memory location. One way to do this is to allocate some 
memory on the global heap before you run the application again. For example, 
you can run the Heap Walker utility, which is included in the Windows SDK, and 
use the commands in the Alloc menu to allocate a chunk out of the global heap. 
Then, when your application executes, its global-memory blocks will be allo- 
cated at different locations than they were before. With luck, the wild pointer 
will refer to a block of protected memory, and CPU memory protection will help 
you trap the bug. 


Another technique is to run the same application in a different CPU mode. For 
example, if you’re debugging an application in enhanced mode, try running it 
again either in standard mode or in real mode. This approach works because the 
selector or segment value of a far pointer depends on the CPU mode. Although a 
wild pointer might contain a valid selector value in one CPU mode, the value 
might be invalid in a different CPU mode and generate a memory-protection 
error. 


You can trap a few wild pointers by running the debugging version of Windows 
in real mode. For example, you can sometimes cause a wild pointer to manifest 
itself by using the Shaker utility in the Windows SDK to shuffle the global heap. 
Shaker rapidly allocates and frees random blocks of global memory. This causes 
the memory manager to frequently relocate moveable global-memory blocks, so 
an application that contains a wild pointer fails sooner than it would without the 
Shaker utility. 


Another real-mode technique is to use ValidateCodeSegments and Validate- 
FreeSpaces. ValidateCodeSegments causes Windows to compute a checksum on 
all global-memory blocks that contain executable code. If the checksum has 
changed, the debugging kernel issues fatal-exit error “Segment contents invalid” 
(error code 0x0409). To use ValidateCodeSegments, you must include the follow- 
ing statement in the /kernel/ section of WIN.INI: 


EnableSegmentChecksum=1 
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You can then insert calls to ValidateCodeSegments into strategic locations in 
your source code. If ValidateCodeSegments fails during your program’s execu- 
tion, you can track down the bug by inserting calls to ValidateCodeSegments un- 
til the wild pointer is isolated. 


A related real-mode debugging technique is to use ValidateFreeSpaces. A call to 
ValidateFreeSpaces checks all free blocks in global memory for spurious data 
stored because of a wild pointer. As with ValidateCodeSegments, you should in- 
sert calls to ValidateFreeSpaces in your source code as frequently as you need to 
check for the use of a wild pointer. 


To use ValidateFreeSpaces, you must include two statements in the /kernel] sec- 
tion of WIN.INI: 


EnableFreeChecking=1 
EnableHeapChecking=1 


These statements cause Windows to store the value OCCH (hexadecimal CC) in 
each byte of each unused global-memory block in the global heap. When you 
call ValidateFreeSpaces, Windows verifies that the free-memory blocks are still 
filled with OCCH and issues a fatal-exit error if they are not. The value 0CCH is 
used because it represents a debugging breakpoint instruction in the 8086 
family of CPUs. If you are using SYMDEB to debug a real-mode application and 
the application jumps to an invalid address in a block of memory that contains 

_ the value OCCH, the resulting debugging break lets you examine the stack and 
trace backward to the function that jumped to the invalid address. In this situa- 
tion, the invalid address is likely to have resulted from overwriting a return ad- 
dress on the stack. 


A robust, industrial-strength Windows application must run properly in a variety 
of unfavorable situations. The best way to ensure that a Windows program can 
resist the slings and arrows of outrageous users is to test, redesign, and debug the 
application in the face of all the adverse circumstances you can anticipate. 


CPU Modes 


Before you distribute a Windows application to its users, be certain the applica- 
tion works properly in real, standard, and enhanced modes. If you developed 
the application in real mode, running it in standard and enhanced modes can 
catch memory-protection errors and wild pointers that might escape your atten- 
tion in real mode. If you developed the program in standard or enhanced modes, 


2: DEBUGGING 


testing it in real mode can unmask errors such as wild pointers caused by the © 
movement of global-memory blocks and failure to match calls to GlobalLock and 
GlobalUnlock. 


It is also a good idea to validate your application by running it in real mode with 
LIM 4.0 expanded memory. This is a must if your application allocates shared 
global-memory blocks for DDE communications or if you are testing a dynamic 
link library that allocates global memory when called by an application. If an ap- 
plication works perfectly in the other CPU modes but fails in real mode with ex- 
panded memory, look for improper global-memory allocations, such as failing to 
use GMEM_DDESHARE or GMEM_NOT_BANKED as a parameter in the alloca- 
tion of a shared global-memory block. 


Input Overflow 


A Windows application becomes susceptible to input overflow whenever a user 
can type or click the mouse button faster than the application can respond. Some 
Windows users are very fast typists. Others are very slow typists who uninten- 
tionally press keys so long that the keys autorepeat. Still others are mouse users 
who do not yet have the hand-to-eye coordination necessary to position the 
mouse and to click or double-click accurately. All these users can crash a Win- 
dows application that is not carefully designed to withstand input overflow. 


For example, any Windows application that uses a push button to initiate a 
prolonged operation is at risk of input overflow because a user can inadvertently 
initiate the same operation several times by repeatedly clicking a mouse button 
or holding down the Enter key. To avoid this problem, call EnableWindow 
to disable the button when it is clicked and to reenable the button only after the 
prolonged operation has completed: 


case WM_COMMAND: 
if( IDBUTTON == wParam ) 
{ 


EnableWindow( (HWND) LOWORD(1Param), FALSE ); 


/* carry out a prolonged operation */ 


EnableWindow( (HWND) LOWORD(1Param), TRUE ); 


Low-Memory Errors 


Another way to bulletproof your application is to run it when global memory is 
scarce. When memory is at a premium, Windows’ memory manager is much 
more likely to move and discard your application’s moveable and discardable 
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global-memory blocks than it is when plenty of global memory is available. This 
means that bugs arising from the careless use of GlobalAlloc and GlobalReAlloc 
and wild pointers related to the movement of global-memory blocks are more 
likely to appear. 


To verify that an application runs in a low-memory situation, run Heap Walker 
along with the application. Select Allocate All Of Memory in Heap Walker’s Alloc 
menu. Then run the application and watch for bugs. The application will proba- 
bly run very slowly as Windows’ memory manager frequently moves or discards 
the application’s code and data. If the application runs too slowly to be usable, 
you can speed it up a bit by using Heap Walker to free 25 or 50 KB. 


Running the Wrong Way 


Before you let an unsuspecting user run a Windows application, try to anticipate 
how the user might make the application fail. This may not be easy if you’re the 
one who designed the application because you naturally know the right way to 
run it. In this case, you might want to find a friend who will look at the applica- 
tion with a fresh viewpoint and ask some hard questions about what will happen 
when the application is run the wrong way. 


For example: Does everything still work properly when the user runs multiple 
instances of your application? Does the application work acceptably if the user 
stores data files on a floppy disk instead of on a hard disk? What happens if the 
user’s hard disk runs out of space? When the user halts the application by ending 
the Windows session, does the application terminate gracefully, without leaving 
open files or GDI objects behind? Does it recover properly from hardware 
failures such as communication line drops, printer errors, and floppy-disk errors? 


It may require some extra programming effort to be able to give good answers to 
questions like these, but bulletproofing will certainly save you trouble in the long 
run. The more experience you gain in debugging and careful bulletproofing in 
the Windows environment, the better your Windows applications will become. 


Dynamic Link 
Libraries (DLLs) 


‘ 
L 


feo 


seontanence mes aieas mss 


3: DYNAMIC LINK LIBRARIES (DLLs) 


The dynamic link library (DLL) is Windows’ basic tool for sharing executable 
code and data. DLLs can be used to support shared subroutines, window classes, 
and read-only resources such as fonts, strings, and bitmaps. DLLs provide a way 
to extend and customize the Windows environment because the functions and 
resources you implement in DLLs can be used by applications in the same way as 
the ones predefined in the Windows API. 


Like a stand-alone Windows application, a Windows dynamic link library is a 
Windows module that consists of executable code or data that Windows can load 
into memory. Functions defined in a DLL have full access to the Windows API. 
They can allocate memory, load resources, process input, and generate output. 
The important conceptual difference between a dynamic link library and a 
stand-alone application is that, unlike an application, a DLL is not a task. DLLs do 
not contain message-dispatching loops that call GetMessage or DispatchMessage. 
Instead, a DLL contains functions, fonts, bitmaps, or other resources that are 
called or loaded on demand by functions in other modules. 


Structure of a Dynamic Link Library 


The structure of a DLL resembles that of a stand-alone application. The differ- 

ence is that a DLL has no WinMain function. Instead, DLLs contain an initializa- 
tion function, LibMain, which Windows calls when it first loads the library into 
memory. DLLs must also contain an exit function, WEP, which Windows calls 
just before it discards the library from memory. The source code for 
DLLBASE.DLL, a baseline dynamic link library, shown in Figure 3-1, contains ex- 
amples of both LibMain and WEP. 


[PERE HERE E TERRE HERR E EERE EEE EERE EEE E EEE E EERE REED HERES HEE E HEE EEE E EEE EEE EH 


* * 
* INIT.C * 
* * 


ERED REET OEE R EEE EEE EEE EERE EERE HEE HE DEERE ERE REESE HEHE RHODE SORE E EERE RHEE EEL 


#define NOCOMM 
#include <windows .h> 


/*** GLOBAL VARIABLES ***/ 
HANDLE hDLLIinst; 


Figure 3-1. (continued) 
Source code for DLLBASE.DLL. 
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Figure 3-1. continued 


/*** FUNCTION PROTOTYPES ***/ 
BOOL PASCAL FAR LibMain( HANDLE, WORD, WORD, LPSTR ); 


[PEFR EEE TOREEH REET CEES EEE SENT REFEREES ESTE SEES SET EEF ATES SEER ESSA EHH E DEERE EES 


* LibMain * 
* Called by LibEntry when this DLL is loaded. * 
2 * 


HEPHEE OEP OEEEEEROEES TEP EEE POE PES H EH ESE SEES TEREES HSER EERE EE ERE REET DERE ETE EEE Ee / 


BOOL PASCAL FAR 
LibMain(. HANDLE hInst, WORD wDS, WORD wHeapSize, LPSTR lpCmdTail ) 


{ 
BOOL bRVal = TRUE; 
/* if LibEntry has called LocalInit, unlock the default data segment */ 
if( wHeapSize ) 
-bRVal = UnlockSegment ( wDS ); 
/* save the DLL instance handle in a global variable +/ 
hDLLInst = hinst; : 
/* (other initialization would go here) */ 
- return bRVal; 
} 


[PERE ER ERE R OEE ERE E RHEE ERE EE EEE EERE EERE EERE TERETE PEER E EERE EEE EE RHEE EEE HER ED 


* * 
* DLLBASE.C . 
*-- Simple Windows DLL. * 
* * 
* Exports: Easter . 
is ShowDLLIcon : 
* * 


HHEREEHEERET RHEE EH ERE REEH ERATE HAE E SHEER EERE RES EH ERE EERE REE H ORE TE HHH ERE O RE RE Ee / 


#define NOCOMM 
#include <windows .h> 


(continued) 
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Figure 3-1. continued 


/*** GLOBAL VARIABLES *+**/ 
extern HANDLE hDLLInst; /* defined in LIBMAIN.C +/ 


/*** FUNCTION PROTOTYPES ***/ 
DWORD PASCAL FAR Easter( int ); 
void PASCAL FAR ShowDLLIcon( HWND, int, int, int ); 


[PRR E ERE EER EERO R EEE E EEE REESE EEE EERO PEE EE SHEE E TED PEE EE ERO E ETRE EERE R EEE EEE 


* * 
* Easter + 
* Returns the date of Easter for the specified year >= 1583. 7 
* The return value is formatted as MAKELONG( day, month ). * 
* * 


* Source: Duffett-Smith, "Practical Astronomy with Your Calculator," * 
* Copyright 1979, Cambridge University Press + 


* * 


PERE RHEEE REE E EERE EERE EEE EH EEE RE EERE REDE EEE EERE EERE PERE RE RHEE E EERE REREAD f 


DWORD PASCAL FAR Easter( int y ) 


{ 
int a,b,c,d,e,f£,g,h,i,k,1,m,n,p; 
a=y % 19; 
b=y / 100; 
c= y % 100; 
d=b/ 4; 
e=b % 4; 
£ = (b + 8) / 25; 
g=(b- £+1) / 3; 
h= (19ta +b -d-g +15) % 30; 
i=c/ 4; 
k=c % 4; 
1 = (32 + 2*e + 2*i - h - k) & 7; 
m= (a + 11*h + 22*1) / 451; 
n= (ht 1 - 7*m +114) / 31;  /* 3=March; 4=April */ 
p= (h +1 - 7#m + 114) % 31; /* day of month (0-30) */ 
return MAKELONG (pt1, n); 
} 


(continued) 
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Figure 3-1. continued 


[FERRE E REE HORE E DORE EEEHOREE DERE EEO DOSES EOPEESEHERDETEEEE THRE RE EHH ESSERE E HEE DE 


* en taet PEE ee * 
* ShowDLLIcon ae ee id 
* Displays the specified icon at the specified coordinates. * 
* . * 


HERPES RHEE ETRE EER EEE E REESE ERE SERED SER EESH ORES EH HEERE HERES ETE ER TEER RES ER ERE HE / 


void PASCAL FAR ShowDLLIcon( HDC hDC, int nID, int nX, int nY ) 


{ 
HICON hiIcon; 


hIcon = LoadIcon( hDLLInst, MAKEINTRESOURCE(nID) ); 
DrawIcon( hDC, nX, nY, hIcon ); 
FreeResource( hIcon ); 


[PEER E ERE EERE HEE EEE REE ETHER EEO EES EEE RES SEE SEES EEE EE HERE E EERE HEHE EEE EEE 


* * 
* WEP .C * 
* Windows exit procedure for Windows 3.x. . 
* * 
* Exports: WEP RESIDENTNAME 7 
* * 
* Notes: This function must reside in a fixed code segment. * 
+ * 


AREER EERE EEE RHR E EEE DERE REET EEE EERE R REE RE REE EEE ERE SESE E THERE RHR H ER ERE HEE EE 


#define NOCOMM 
#include <windows.h> 


Y heheheh tekotoehelhahelehetekehahetsRehahahetetehehedchetakehebutetatehehehetatahaheheteheietehebehehahtetehahathetettteteieietiteta iets ttated 


* * 
* WEP : id 
* . Called by Windows when this DLL is unloaded. 7 


ERNE EEE EERE REDE RHEE HEATHEN EERE ARES HERR EE EERE REE ERE REE RR EE ERE REE EER ER RE REE E/ 


int PASCAL FAR WEP( int nParam ) 


{ 
int nRVal; 


(continued) 
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Figure 3-1. continued 


switch( nParam ) 
{ 
case WEP_SYSTEM_EXIT: 
case WEP_FREE DLL: 
default : 
nRVal = 1; 
} 


return nRVal; 


[JRA F PERO R EERE HE EAH HEE E THEE EERES EEE R HEE E EET ET HOHE EEE H EEF EOE REDE E REE EERE RRO EE 


* * 
* DLLBASE.RC resource script J 
* * 


FOHRHOHFEES SEEPS ERPS FEET SLES ERESESEPESSERESE EERE TEESE HERETEHT ERE SHEE ESE / 


STRINGTABLE 

{ 
100, "Wer zuletzt lacht lacht am Besten." 
101, "He who laughs last laughs best." 
102, "Riva bien qui rira le dernier." 


} 


100 ICON deutsch.ico 
101 ICON usa.ico 
102 ICON france.ico 


LESS AAAS ASAE AES ESE EOS SS ESSE SAE ES RAE ESSE EEE SOE SEO Oe SOO SETS Oe 8 OO 8 eee 
. * 
a 
; DLLBASE.DEF module-definition file * 
* * 
t 
PSSST EOS SESE S ES AOE SESS O SEAS SESS ESOS ERE ESE ESE REEL LE RESELL EL ELS TE EOE SEES OOS 


LIBRARY DLLBASE 

DESCRIPTION ‘DLLBASE version 1.0' 

EXETYPE WINDOWS 

CODE LOADONCALL MOVEABLE DISCARDABLE 


DATA PRELOAD MOVEABLE. SINGLE 
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Figure 3-1. continued 


HEAPSIZE 0 

SEGMENTS INIT_TEXT PRELOAD DISCARDABLE 
WEP. TEXT -° PRELOAD FIXED 

EXPORTS WEP @1. RESIDENTNAME 
Easter @2 
ShowDLLIcon @3 


When Windows loads a library into memory, it transfers control to a short startup 
routine called LibEntry. This startup routine is defined in an object file named 
LIBENTRY.OBJ, which Microsoft supplies as part of the Windows SDK. (You 
must link LIBENTRY.OBJ into your DLL on the LINK command line.) LibEntry 
performs two actions. If you declare a nonzero heap size in the library’s module- 
definition file, LibEntry calls LocalInit to initialize a local heap in the DLL’s 
default data segment. Then LibEntry transfers control to the library’s initializa- 
tion function, LibMain. 


Because LibMain always executes at the time Windows loads the library, the 
LibMain function can carry out any initialization required by other functions in 
the library. You can use LibMain to initialize global variables, register window 
classes, or perform any other initialization needed by the library. LibMain 
returns a nonzero value to indicate that initialization is successful. If LibMain 
returns 0, Windows does not load the library. 


Typically, LibMain also calls UnlockData or UnlockSegment for libraries that use 
a local heap. This is necessary because LibEntry calls LocalInit if the library 
contains a local heap, and LocalInit leaves the DLL’s default data segment 
locked. For a DLL that might be used when Windows is running in real mode, it 
is best to leave the default data segment unlocked so that Windows’ memory 
manager can move it if necessary. In the sample library, DLLBASE, LibMain de- 
termines whether to call UnlockSegment by testing the value of the wHeapSize 
parameter. 


Library Functions 


If a function defined in a DLL is to be called by another Windows module, the 
function must be exported so that Windows can dynamically link the caller with 
- the called function. Such functions in DLLs must also be defined as far functions 
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because the library code segment in which the function is defined might not be 
the same as the segment from which the function will be called. In DLLBASE, the 
application-callable functions are Easter and ShowDLLIcon, both of which are 
declared with the keywords PASCAL FAR and exported in the library’s module- 
definition file, DLLBASE.DEF. 


Although DLLBASE defines only two application-callable functions, you can in- 

corporate as many functions as you want into a library as long as you export 

each application-callable function. The only functions that do not need to be ex- 

ported are those that are called only by other functions in the same library. How- 

ever, there is no penalty for exporting such functions. In a DLL, exported 

functions can be called by other functions in the same DLL as well as by func- 
tions in other modules. 


Library Resources 


DLLBASE includes a loadable STRINGTABLE resource and three ICON re- 
sources, defined in the resource file DLLBASE.RC. The resources are built into 
the DLLBASE.DLL file, just as they would be in a Windows application. When 
Windows loads DLLBASE.DLL, the resources become available to any applica- 
tion. To access the STRINGTABLE resource, for example, an application must 
first call LoadLibrary to ensure that Windows has loaded the library and to ob- 
tain the library’s module handle. The application then uses the handle in calling 
LoadString to access the string table. A function in the same DLL accesses a DLL 
resource by using the DLL’s instance handle instead of calling LoadLibrary to 
- obtain a module handle. The function ShowDLILIcon in DLLBASE.C shows how 
to do this. 


The Exit Procedure 


Every DLL must export a callback function named WEP (which stands for Win-. 
dows Exit Procedure). Windows calls a library’s WEP function while it is 
unloading the library from memory. The purpose of the exit procedure is to pro- 
vide a way for a DLL to perform any final actions that need to be carried out 
before the library is discarded. Such actions might include freeing any memory 
blocks that have been allocated in the library, discarding strings and bitmaps, or 
closing open files. 


There are two important restrictions on what a WEP function can do: A WEP 
function must not call LoadLibrary or FreeLibrary, and WEP should not call a 
function in another DLL if the other DLL is being unloaded at the same time. For 
example, imagine that you define a function named MyPrintf in DLL1.DLL and 
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that you import the MyPrinif function into a second DLL using an import library 
or an IMPORTS statement in the second DLL’s .DEF file: 


IMPORTS DLL1.MyPrintf£ 


In this situation, it would be an error for the second DLL’s WEP function to call 
MyPrintf: 


int PASCAL FAR WEP( int nParam ) 


/* WRONG */ 
MyPrintf( "The second DLL is unloading" ); 


return 1; 


} 


Windows passes a parameter to WEP that indicates the circumstance under 
which the library is being unloaded. If the Windows session is terminating, the 
parameter has the value WEP_SYSTEM_EXIT. If all applications that use the li- 
brary have terminated or have freed the library, the parameter’s value is 
WEP_FREE_DLL. In all cases, the WEP function should return the value 1. 


The Library Reference Count 


For each DLL in memory, Windows maintains a reference count that indicates the 
number of tasks that are dynamically linked to the library. Windows increments 
the reference count when it loads an instance of an application that calls a li- 
brary function and decrements the count when the instance terminates. The ref- 
erence count is also incremented by the LoadLibrary function and decremented 
by the FreeLibrary function. A DLL can examine its own reference count by call- 
ing GetModuleUsage with the library’s module handle as a parameter. 


If you have never used a DLL, you might wonder why it is necessary to take the 
trouble to build a DLL just to share functions or data. Why not build a stand-alone 
Windows application that contains the executable code for the functions you 
want to share? You could export each of the shared functions with an appropriate 
EXPORTS statement in the application’s module-definition (DEF) file. Then, in 
any application that called one of the shareable functions, you would include a 
corresponding IMPORTS statement in the .DEF file. 


This technique actually works, but it is very unreliable. One obvious problem is 
that it is hard to guarantee that the application that contains the shared functions 
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will be loaded in memory at the moment another application attempts to call 
them. Another problem is more subtle: When expanded memory is available, 
Windows’ memory manager uses bank-switched expanded memory to contain 
an application’s code segments. When the application is not actively processing a 
Windows message, the expanded-memory banks containing the code segments 
are not mapped into the CPU address space. Any shared functions in a banked- 
out code segment would be inaccessible to other applications. 


Dynamic link libraries were designed to avoid these problems. After a DLL is 
loaded into memory, it remains loaded until it is released by every application 
that uses it. Also, when an application calls a DLL function, Windows’ memory 
manager ensures that the executable code segment that contains the function is 
always accessible, even if the memory manager has discarded the segment or 
swapped it into a bank of expanded memory. 


In this way, Windows’ memory manager takes care of the memory-management 
problems involved with sharing library functions. Your job is to structure your 
DLL's code and data segments so as to use memory efficiently. 


Memory Models for DLLs 


For a small DLL, it is simplest to use the small memory model so that the library 
is loaded into memory in one code segment and one default data segment. For a 
large DLL, however, you can optimize memory usage by compiling the DLL with 
a medium memory model and dividing the DLL’s source code into two or more 
separately compiled segments. 


When you use the medium memory model, each segment of executable code 
should be no larger than about 4 KB. This is the size of the virtual memory block 
that Windows’ memory manager uses when Windows executes in enhanced 
mode on an 80386 or 80486 microprocessor. When you link a medium memory 
model DLL, mark its code segments as moveable with the following CODE state- 
ment in the module-definition file: 


CODE MOVEABLE 


This statement marks all code segments in the DLL as moveable. You should 
override this statement by using a SEGMENTS statement for the following 
segments: 


The code segment that contains the WEP function. 


Code segments that contain interrupt handlers. 
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m™ Code segments that contain the callback function specified in a call to 
GlobalNotify. 


These code segments should be declared as fixed rather than moveable. This is 
illustrated in the module-definition file DLLBASE.DEF in Figure 3-1. 


You can further tune a DLL’s memory management in the module-definition file 
by using the PRELOAD and DISCARDABLE attributes for INIT_TEXT, the code 
segment that contains the library startup function LibEntry. The PRELOAD at- 
tribute makes sense because this segment contains code that executes when the 
library is first loaded. The DISCARDABLE attribute is used because the segment 
will not be used again as long as the library remains in memory. The same 
reasoning applies to the segment that contains LibMain, so you might want to 
compile LibMain along with LibEntry in the discardable INIT_TEXT segment. 
In the DLLBASE example, this is accomplished by defining LibMain in a file 
named INIT.C so that the Microsoft C compiler names the corresponding seg- 
ment INIT_TEXT. You could achieve the same result using the compiler’s /NT 
(name code segment) command-line switch. 


If a DLL references large amounts of static data, you might consider using a large 
memory model. However, far data segments in the large memory model are fixed 
segments. It is better to use a small or medium memory model and load static 
data as a binary resource. Avoiding fixed data segments makes Windows’ virtual 
memory management more efficient. 


The Default Data Segment 


Unlike stand-alone applications, Windows libraries cannot have multiple in- 
stances—that is, a Windows library has only one default data segment. The data 
in a library’s default data segment is shared by all applications that use the li- 
brary. Because only one copy of a library’s data segment can exist, you must use 
the SINGLE attribute with the DATA statement in a library’s .DEF file. 


With DLLs, you have another option. If a library uses no static data and calls no 
functions that need to use the library’s local heap, you can avoid using a data 
segment at all. To do this, enter this statement in your module-definition file: 


DATA NONE 


You can also avoid using a data segment by adding the keyword NODATA to 
each EXPORTS statement. If you create a library without a data segment, be very 
careful how you use data in library functions. The following C-language function 
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contains several examples of what you cannot do in a library without a default 
data segment; the comments explain why not: 


int nBytes; /* external variables are stored 
in the default data segment */ 
char szName[] = "Alpha"; /* initialized variables are stored 


in the default data segment */ 


int MyFunc() 


{ 
static LOCALHANDLE hx; /* static variables are stored 
in the default data segment */ 


lstrcemp( szName, "Beta" ); /* "Beta" is implicitly stored 
in the default data segment */ 
} 


There is yet another memory-management optimization that involves the DLL’s 
default data segment. A DLL’s initialization function, ZibMain, should usually 
contain a call to UnlockData or UnlockSegment: 


UnlockSegment ( wDS ); 


This call ensures that the library’s default data segment remains unlocked while 
the library remains in memory. Although this may not matter when Windows is 
run in protected mode, it can improve memory management in a real-mode 
Windows environment. In real mode, unlocking the data segment lets Windows’ 
memory manager move the segment to a different location in the global heap in 
response to other modules’ demands for global memory. 


If you are designing a DLL for real-mode execution and you are using a far 
pointer to an item in the default data segment, you might want to lock the data 
segment temporarily to ensure that the far pointer remains valid while it is being 
used. You can do this by surrounding the code that uses the far pointer with a 
pair of calls to LockData and UnlockData or LockSegment and UnlockSegment: 


static char Buffer[64]; /* (stored in the DLL's 
default data segment) */ 


LockSegment( wDS ); | /* lock the default data segment */ 
MyFunction( (LPSTR)&Buffer ); /* use a far pointer */ 
UnlockSegment ( wDS ); /* unlock the data segment */ 
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Calling Library Functions 


Shared functions in dynamic link libraries must be exported and must be called 
with far calls. In this regard, they are just like exported functions in stand-alone 
Windows applications. Nevertheless, there are differences in the methods that 
exported library functions use to manage the default data segment and the stack. 


Windows associates a different default data segment with each DLL and each in- 
stance of a task. This is accomplished by a short prolog of executable code that 
precedes every exported far function. The function prolog sets up the CPU’s DS 
register so that the function uses the proper default data segment when it refer- 
ences static data and data on the stack. 


Every far function in a Windows module is preceded by a function prolog. You 
need not code the prolog explicitly—it is generated by your compiler or, if you 
program in assembly language, by a macro expansion. (The Microsoft C com- 
piler’s /Gw switch instructs the compiler to generate Windows function prologs.) 
The prolog generated by the compiler, which is shown in Figure 3-2, does not 
change the default data-segment value in register DS. However, if a far function 
is exported, Windows modifies the executable code in the function prolog at the 
time it loads the function into memory so that the prolog stores the appropriate 
data-segment value in DS when it executes. 


push ds 7 copy DS to AX 
pop ax 
nop 
inc bp ; save BP+1 on stack 
push bp 
mov bp,sp ; save current stack pointer in BP 
push ds ; save current DS 
mov ds,ax 7; copy AX to DS 
Figure 3-2. 


Nonexported far-function prolog. This prolog does not change the default data- 
segment value in register DS. 


Windows modifies exported far-function prologs differently in applications and — 
in DLLs. In an application, the prolog copies a default data-segment value from 
register AX to register DS, as in Figure 3-3. The data-segment value, which corre- 
sponds to the instance of the application in which the function is executing, is 
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nop 
nop 
nop 
inc bp ; save BP+1 on stack 
push bp 
mov bp,sp ; save current stack pointer in BP 
push ds ; Save current DS 
mov ds,ax ; copy AX to DS 
Figure 3-3. 


Exported far-function prolog in a Windows application. This prolog changes 
the default data segment by copying the value in register AX to register DS. 


placed in AX in a fragment of executable code called an instance thunk (shown 
in Figure 3-4). For each exported far function, an application must create an in- 
stance thunk by calling MakeProcInstance, unless the function is a window 
function whose address was passed as a parameter to RegisterClass. 


mov ax,xXxxx ; store the data-segment value in AX 
jmp far ptr function ; jump to exported far-function prolog 
Figure 3-4. 


An instance thunk. This piece of executable code is created by MakeProc- 
Instance. The value stored in AX is used in the exported-function prolog shown 
in Figure 3-3. 


A different arrangement is used for exported far functions in a DLL. There is only 
one data segment associated with a dynamic link library, so there is no need for 
Windows to support multiple instance thunks, and there also is no need to call 
MakeProcInstance for exported library functions. In a DLL, the data-segment 
value is built into the prolog of each far function, as in Figure 3-5. The structural 
differences between the different far-function prologs are worth remembering 
when you debug a program that contains a wild pointer caused by an im- 
properly exported far function. In this situation, you can verify that a far func- 
tion is correctly exported by examining the function’s prolog. 


mov ax, xXxxx ; store the data-segment value in AX 
inc bp ; save BP+1 on stack 
push bp 
mov bp,sp ; save current stack pointer in BP 
push ds ; Save current DS 
mov ds,ax ; copy AX to DS 

Figure 3-5. 


Exported far-function prolog in a dynamic link library. This prolog stores the 
library’s default data-segment value in register DS. 
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Parameter-Passing Conventions 


When you pass parameters between dynamic link libraries and other Windows 
modules, keep in mind that the library’s code and data segments are not the 
same as those in other modules. All pointers to library data items and all calls to 
library functions must use far pointers so that they explicitly specify the segment 
to which they refer. 


The order in which you specify parameters is not constrained by anything in 
Windows as long as the caller and the function being called agree on the pa- 
rameter order. The Windows API generally uses the Pascal parameter-passing 
convention, which is that the leftmost parameter is the first one pushed on the 
stack. You can, however, use the C-language convention, which is that the 
rightmost parameter is the first one pushed on the stack. 


The advantage of the Pascal convention is that the executable code that manages 
the stack across function calls is a few bytes shorter and a little faster than the 
equivalent code required for the C method. The advantage of the C-language 
convention is that it lets you design functions such as printf that support a vari- 
able number of parameters. 


Unless you need a variable-length parameter list, you should use the Pascal con- 
vention. If you use the C convention, remember that the C compiler adds an 
underscore character to the beginning of each function name, so EXPORTS 
module-definition statements for such function names must include the under- 
score. For example, consider the following C function: 


int far cdecl MyPrintf(); 


The corresponding EXPORTS statement in the module-definition file would con- 
tain an underscore: 


EXPORTS _MyPrintf 


The Stack and the Default Data Segment 


In all Windows programs, the stack is where function parameters are passed, 
where a function’s return address is saved when it calls another function, and 
where storage for automatic variables is allocated. The default data segment is 
used for static data, for constants, and for the local heap. In Windows applica- 
tions, which use the small or medium memory model, these two logically dis- 
tinct types of data are maintained in a single segment—that is, the stack is 
located in the default data segment. In this way, stack data and static data can be 
addressed by using offsets within the same segment. 
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This is a handy arrangement because a program can store the same value in the 
CPU’s DS (data segment) register and SS (stack segment) register and then use ei- 
ther register to address both the stack and the rest of the data in the default data 
segment. This makes it easier for a compiler such as the Microsoft C compiler to 
translate source code into executable code because the compiler can generate 
code that uses the DS and SS registers interchangeably to address both static data 
(stored in the default data segment) and automatic data (stored on the stack). 


A DLL differs from a Windows application in that a DLL does not have its own 
stack. Instead, each function in a DLL uses its caller’s stack. This can lead to ad- 
dressing problems because it contradicts the compiler’s assumption that the DS 
and SS registers contain the same segment value. When you write DLL source 
code, you must keep this potential problem in mind. 


In general, the way to avoid DLL addressing problems is to use far pointers to 
DLL data items instead of near pointers. If you use a near pointer, the compiler 
might not be able to determine whether the pointer refers to a location in the 
stack or a location in the default data segment. In this case, a compiler might ar- 
bitrarily assume that the reference is to the default data segment instead of the 
stack. This is not a valid assumption in a DLL, where the stack segment is not the 
same as the default data segment. 


In contrast, when you use a far pointer, you refer explicitly to a particular seg- 
ment as well as to the offset of a data item within the segment. When a compiler 
compiles a far pointer, it makes no assumptions about segment addressing, and 
you make no assumptions about the compiler’s assumptions. This is the strategy 
adopted by the designers of the Windows API, in which functions ao always 
expect far pointers as parameters. 


The problem with using far pointers everywhere in a DLL is that DLLs are typi- 
cally compiled with the small or medium memory models, and small-model and 
medium-model C runtime library functions expect near pointers as parameters. 
You can sometimes solve this problem by using a far-pointer equivalent of a li- 
brary function. For example, the _fmemmove function in the Microsoft C librar- 
ies is a far-pointer equivalent of the memmove function. 


If you do use near pointers, be sure they always refer to data items in the DLL's 
data segment and not to a variable or an array on the stack. This means that near 
pointers should refer only to static variables and arrays and to memory blocks 
allocated in the DLL’s local heap with LocalAlloc. The Microsoft C compiler can 
help you to avoid inaccurate use of near pointers. When you use the /Aw 
command-line switch, the compiler will warn you if you use a near pointer to a 
data item on the stack. 
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Figure 3-6 is an example of how to use a far pointer to access data on the stack. 
The function AuxPrintf uses OutputDebugString to send a formatted text string 
to the debugging display. 


void FAR cdecl AuxPrintf( LPSTR szFmt, ... ) 


{ 
char szBuf [128]; 


LPSTR FAR * pArg1; 


/* point to the second parameter on the stack */ 
pArgi = ((LPSTR FAR *)&szFmt) + 1; 


/* format the output string */ 
wvsprintf( szBuf, szFmt, (LPSTR)pArg1 ); 


/* display the formatted string */ 
OutputDebugString( szBuf ); 
} 


Figure 3-6. 
Using a far pointer to data on the stack. The address of szFmt is cast to a far 
pointer when it is assigned to the variable pArg]. 


The formatting is carried out through a call to wusprintf, which expects a pointer 
to an argument list as a parameter. AuxPrintf stores the pointer as a far pointer: 


pArg1 = ((LPSTR FAR *)&szFmt) + 1; 


The far pointer to sz¥mt is stored correctly as a reference to the stack segment. 
Compare this to a similar statement that stores a near pointer instead of a far 
pointer: 


pArgi = ((LPSTR *)&szFmt) + 1; /* WRONG! */ 


The difference between these two statements becomes apparent in the call to 
wosprint: 

wvsprintf( szBuf, szFmt, (LPSTR)pArgi ); 
In the first example, the value of pArg1 is passed to wusprintif as a far pointer. 
This works perfectly. In the second example, however, the C compiler converts 
the near pointer to a far pointer by incorrectly assuming that the pointer lies in 


the default data segment. The point is clear: Use far pointers to address stack 
variables in Windows DLLs. 
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Sharing Functions and Data 


It is not hard to share functions or data in a DLL. Often all you need to use are 
exported far functions and far data pointers. However, Windows provides impor- 
tant alternatives to the use of far pointers—namely, global-memory handles and 
resources. The best method for sharing a particular function or data item de- 
pends on whether the item lies outside the DLL or within it. 


Pointers to Data Outside a DLL 


If you keep in mind how a DLL uses its default data segment and stack, you can 
use far data pointers to pass data to DLL functions. There are situations, however, 
where relying on a far pointer can lead to problems. 


One such situation occurs when Windows executes in real mode. In real mode, 
a far pointer to a block of memory consists of a physical-segment address plus an 
offset within the segment. The physical-segment value can become invalid if 
Windows’ memory manager moves the block of memory to which the pointer 
refers. To avoid this problem, be sure that far pointers always refer to memory 
blocks whose location in memory is fixed. 


The easiest way to fix the location of a block of memory is either to use the 
FIXED keyword to declare a fixed segment in a module-definition file or to use 
the GMEM_FIXED flag in a call to GlobalAlloc. The problem with doing this is 
that such segments remain at the same physical location in memory from the 
time they are allocated until the time they are freed. This limits the memory 
manager’s ability to rearrange the global heap dynamically in response to the 
memory requirements of multiple applications. 


A better approach is to use the keyword MOVEABLE in the module-definition 
file and the GMEM_MOVEABLE flag in GlobalAlloc. To pass a far pointer to data 
in a moveable memory block, you must first call GlobalLock to lock the block’s 
global-memory handle: 


1IpDATA = GlobalLock( hData ); 

MyDLLFunc( lpData ); /* call a DLL function named 
MyDLLFunc */ 

GlobalUnlock( hData ); 


To pass a far pointer to data in an application’s default data segment, call 
LockSegment(-D) or LockData prior to calling the DLL function: 


LockData () ; 

MyDLLFunc( (LPSTR) &Data ); /* call a DLL function named 
MyDLLFunc */ 

UnlockData () ; 
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A simpler approach to passing data from an application to a DLL is to use a 
handle to a global-memory block as a parameter instead of a far pointer. With 
this technique, the DLL function itself can lock the memory handle: 


void PASCAL FAR MyDLLFunction ( GLOBALHANDLE hData ) 


{ 
LPSTR lpData; 


lpData = GlobalLock( hData ); 
/* use lpData */ 


GlobalUnlock( hData ); 
} 


Dereferencing the global-memory handle involves a bit of extra programming— 
the DLL must call GlobalLock and GlobalUnlock each time it accesses data 
passed to it from an application. However, using a global handle is a safer tech- 
nique than using a far data pointer because you can control how Windows’ 
memory manager manages the memory block that contains the data item. This is 
most important in real mode, where far pointers can be invalidated by the nor- 
mal operation of Windows’ memory manager. In particular, you can use the 
GMEM_DISCARDABLE or GMEM_NOT_BANKED flags with GlobalAlloc to 
specify whether the memory manager is allowed to discard a particular memory 
block or store it in a bank of expanded memory. . 


Use GlobalAlloc with the GMEM_DDESHARE flag to ensure that a global- 
memory block remains accessible within a DLL when Windows is using real- 
mode expanded memory. Consider, for example, what might happen if a far 
pointer referred to data that was owned by an application executing in bank- 
switched expanded memory. If the application called a DLL function that in turn 
caused a different application to execute, the calling application might be 
banked out of memory and the far pointer would no longer be valid. Careful use 
of GMEM_NOT_BANKED will avoid this problem. 


Pointers to Data Within a DLL 


When you pass data from a DLL to an application, you must be certain that far 
pointers to such data remain valid while the application is using them. Again, 
this is most important in real mode. For example, you can pass far pointers to 
shared data stored within a DLL’s default data segment as long as you ensure that 
Windows’ memory manager will not move the data segment while the pointer is 
in use. 
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Again, a more general approach to sharing DLL data is for a DLL to allocate 
blocks of global memory to contain shared data. The DLL can then use global 
handles instead of far pointers to refer to the shared data. Although this tech- 
nique involves the extra overhead of allocating a block of global memory and of 
dereferencing a global-memory handle, it decreases the possibility of creating 
wild pointers when Windows is running in real mode. 


Pointers to Functions Outside a DLL 


To pass the address of a function located outside a DLL to a DLL function, you 
must use a far pointer to the function or to the function’s instance thunk. If the 
far function is also in a DLL, you need only pass the address of the function: 


MyDLLFunc( (FARPROC)DialogFunc ); 


If the far function is defined in an application, you must pass the address of an 
instance thunk for the function: 


pThunk = MakeProcInstance( (FARPROC)DialogFunc, hInstance ); 
MyDLLFunc( pThunk ); 
FreeProcInstance( pThunk ); 


Pointers to Functions Within a DLL 


To pass the address of a library function to an application, use a far pointer to the 
function. The application can subsequently call the function by dereferencing 
the far pointer, as in Figure 3-7. Of course, a library need not contain a function 
that returns pointers to other library functions—an application can call 
GetProcAddress to obtain a pointer to any exported DLL function. In either case, 
be sure you export any application-callable library functions with appropriate 
EXPORTS statements in the library’s module-definition file. 


/* in the DLL +/ 
FARPROC PASCAL FAR NthDLLFunction( int n ) 


switch( n ) 
{ 


case 1: 
return Function; 
break; 


Figure 3-7. (continued) 
Returning a DLL function pointer to an application. All of the DLL functions 
are exported in the DLL’s module-definition file. 
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Figure 3-7. continued 


case 2: 
return Function2; 
break; 


default: 


return DefaultFunction; 
break; 


} 


void PASCAL FAR Function1{.... ) 
{ 


} 

void PASCAL FAR Function2(... ) 

{ 

} 

void PASCAL FAR DefaultFunction( ....) 
{ 

} 


/* in the calling application */ 
FARPROC 1pDLLFn; 


/* get a pointer to the first DLL function */ 
1pDLLFn = NthDLLFunction( 1: ); 


/* execute the DLL function */ 
(*lpDLLFn) (...); 


‘ 


Another way to use a DLL to share data is to define resources within the library. 
An application can access a resource in a library by calling LoadLibrary fol- 
lowed by the appropriate load function (LoadBitmap, LoadIcon, LoadString, and 
so on). For example, Figure 3-8 shows how an application would access one of 
the string resources defined in the sample library DLLBASE.DLL. 
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HANDLE hLibrary; 
char szBuf [64]; 


hLibrary = LoadLibrary( "DLLBASE.DLL" ); 

if( 32 >= hLibrary ) 

{ 
LoadString( hLibrary, 101, szBuf, sizeof szBuf ); 
FreeLibrary( hLibrary ); 

} 


Figure 3-8. 

Using a resource defined in a dynamic link library. The value 101 refers to the 
identifier used in the string table resource in DLLBASE.RC. (See Figure 3-1 on 
page 61) 


You can define any resource in a library that you can define in a stand-alone ap- 
plication, including GDI objects, dialog boxes, menus, and user-defined binary 
data. You might even want to create a library that contains only resources. The 
only exported function in such a library would be its WEP function. Such 
resource-only libraries provide an elegant mechanism for sharing globally used 
objects in a portable, low-overhead manner. 


Many libraries are designed as a combination of shared resources and useful 
functions. One specific application of this kind of library is to support a window 
class that describes a user-defined custom control. In fact, custom-control librar- 
ies are important enough in the Windows environment to be the subject of the 
next chapter. 


Custom Controls 
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4: CUSTOM CONTROLS 


Controls are the building blocks of a Windows application's visual interface. The 
predefined control classes—Static, Button, Edit, ScrollBar, ListBox, and Combo- 
Box—are general-purpose tools that you can use in a wide variety of program- 
ming situations. It is hard to imagine a Windows program that does not some- 
where use at least one button, scroll bar, or static text control. 


It is not hard, however, to implement custom controls whose function or ap- 
pearance is tailored to the specific needs of an application. Like the predefined 
controls, custom controls are child windows that perform specific visual input or 
output functions. You can develop a custom control as part of a Windows appli- 
cation, but you can make a custom-control window class available to multiple 
applications by implementing it in a dynamic link library and by making the 
control accessible to resource editors such as the Dialog Editor (DIALOG.EXE) in 
the Windows SDK. 


A Custom Control in a 
Windows Application 


The simplest way to implement a custom control is to have an application call 
RegisterClass to register the custom-control class and then call CreateWindow to 
create one or more control windows. You can use the same methods to test and 
debug the control that you use to test and debug any stand-alone Windows appli- 
cation. You can even add CONTROL statements to DIALOG resources in the ap- 
plication’s resource script to create custom controls in dialog boxes, provided 
that the application registers the control class before it loads the dialog resources 
that use the custom control. 


Figure 4-1 on the following page shows a single example of a custom-control 
class named RYG, whose visual appearance is a familiar red-yellow-green sym- 
bol. A program can set or get the state of an RYG control by sending it one of 
two user-defined messages, RYG_SETSTATE or RYG_GETSTATE. The source 
code in Figure 4-2 on the following pages shows how the RYG class is developed 
within a Windows application. 


In this example, the application is nothing more than a testbed for developing 
the RYG control class. Embedding the control in an application makes it easy to 
test and modify the control’s user interface. When the control class works prop- 
erly, you can use it in a different application simply by copying the relevant 
source code. 
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Figure 4-1. 
A typical RYG control displayed by RYGDEV.EXE. 
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# * 
# NMAKE description for RYGDEV.EXE * 
# * 


FARE EERE RHEE EE ERE E REE HERES EH EERE EERE ESHER ETH HERE ER ER REF EE EERE REET ENE R EEE HERS 


.c.0bj: 
cl /AM /c /G2sw /Osw /W4 /Zlp $*.c 
ALL: rygdev.exe 
ryg.obj: ryg.c rygdev.h 
rygdev.obj: rygdev.c rygdev.h 
rygdev.res: rygdev.rce rygdev.h rygdev.ico 


re /r rygdev.re 
rygdev.exe: ryg.obj rygdev.obj rygdev.res rygdev.def 


link /al:16 /nod /noe rygdev ryg, , , libw mlibcew, rygdev.def 
xe rygdev.res 


Figure 4-2. (continued) 
Source code for RYGDEV.EXE. 
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Figure 4-2. continued 
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* * 
* RYGDEV.C * 
* Simple application that uses the RYG control from RYG.C * 
* Exports: TopLevelWndFn . 
* + 


HEEEEEH EERE HEE REE HERE EERE ERE HE REE ETRE EES EER ER EE EEE HEHE EERE EERE R EE ERE RR EE H / 


#define NOCOMM 

#include <windows .h> 

#include "rygdev.h" 

#define IDRYG 100 

/*** FUNCTION PROTOTYPES +**+/ 

LONG PASCAL FAR TopLevelWndFn( HWND, WORD, WORD, LONG ); 
static HWND Init ( HANDLE, HANDLE, int ); 


/*** GLOBAL VARIABLES **+*/ 


HBRUSH hRYGBrush[3]; 


DWORD dwRGB[3] = { RGB(OxFF,0x00,0x00), /* red */ 
RGB (OxFF, OxFF, 0x00), /* yellow */ 
RGB (0x00, OxFF,0x00) }; /* green */ 

static char szTopLevelClass[] = "RYG:TopLevel"; 

static char szRYGClass[{] = "RYG"; 

static char szAppTitle[] = "RYG"; 


[FREE REO ERE REE EERE EEE EEE EEE EEE REPT E EERO RHEE EE EERE ERE R EEE EERE EERE EER AER EH 


* * 
* WinMain * 
* * 


HHERREHE REED HERE EE ERE EERE RHEE REE EH EE EES E EEE ERE E TPE EE REE E EERE HH EERE He / 


int PASCAL 
WinMain( HANDLE hInst, HANDLE hPrevInst, LPSTR lpszCmdLine, int nCmdShow. ) 


HWND hWnd; 
MSG msg; 
int n} 


(continued) 
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Figure 4-2. continued 


hWnd = Init( hiInst, hPrevInst, nCmdShow ); 
if( 'hWnd_ ) 
return 0; 


/* create brushes */ 
for( n=0; n<3; nt+ ) 
hRYGBrush[n] = CreateSolidBrush( dwRGB[n] ); 


while( GetMessage( &msg, 0, 0, 0) ) 
{ 
TranslateMessage( &msg ); 
DispatchMessage( &msg ); 
} 


/* destroy brushes */ 
for( n=0; n<3; n++ ) 
DeleteObject ( hRY¥GBrush[n] ); 


return msg.wParam; 


[PERE H ERTS HEE REE HOR ETE SHEE EER EEE SR ER EET ER REET EE EEE HERES ER EEE SHED EEE HERE E HEED 


* 


* 


* Init aa: : * 


* 


* 
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static HWND Init( HANDLE hInst, HANDLE hPrevInst, int nCmdShow ) 


{ 


WNDCLASS we; 
HWND hWnd; 


if( 'hPrevInst ) 
{ 
/* register the top-level window class */ 
we.lpszClassName = szTopLevelClass; 
we .hInstance hIinst; 
we. lpfnWndProc TopLevelWndFn; 
we .hCursor LoadCursor(. 0, IDC_ARROW ); 
we hIcon LoadIcon( hinst, "TopLevelicon" ); 
we. 1lpszMenuName "TopLevelMenu"; 


tow mot mn ea 


we. hbrBackground COLOR_WINDOW+1 ; 
we,.style CS_HREDRAW | CS_VREDRAW; 
we .cbhCisExtra = 0; 

we. cbWndExtra = 0; 


(continued) 
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Figure 4-2. continued 


if( !RegisterClass( &we ) ) 
return 0; /* return 0 if unsuccessful */ 


/* xvegister the RYG window class */ 


we.lpszClassName = szRYGClass; 

we. hInstance = hInst; 

we.lpfnWndProc = RYGWndFn; 

we. hCursor = LoadCursor( 0, IDC_ARROW ); 
we. hIcon = 0; 

we.lpszMenuName = NULL; 

we. hbrBackground = COLOR_WINDOW+1 ; 

we.style = 0; 

we.cbClsExtra = 0; 

we, cbWndExtra = sizeof (WORD) ; 


if( !RegisterClass( &we ) ) 
return 0; /* veturn 0 if unsuccessful */ 


} 


/* create and display a top-level window */ 
hWnd = CreateWindow( szTopLevelClass, 
szAppTitle, 
WS_OVERLAPPEDWINDOW, 
CW_USEDEFAULT, 0, CW_USEDEFAULT, 0, 
0, 
0, 
hinst, 
NULL ); 


/* create an RYG window */ 
CreateWindow( szRYGClass, 
, 
WS_CHILD | WS_VISIBLE, 
0, 0, 16, 16, 
hWnd, 
IDRYG, 
hinst, 
NULL ); 


ShowWindow(. hWnd, nCmdShow ); 
UpdateWindow( hWnd ); 


return hWnd; 


(continued) 
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Figure 4-2. continued 
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* * 
* TopLevelWndFn * 
ao * 
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LONG PASCAL FAR 
TopLevelWndF'n( HWND hWnd, WORD wMsg, WORD wParam, LONG lParam ) 
{ « 

LONG 1RVal = OL; 

BOOL bDWP = FALSE; 


switch( wMsg ) 
{ 
case WM_COMMAND: 
SendDlgItemMessage( hWnd, IDRYG, RYG_SETSTATE, wParam, OL ); 
break; 


case WM_SIZE: 
MoveWindow( GetDlgItem( hWnd, IDRYG ), 
0, 0, LOWORD(1Param), HIWORD(1Param), TRUE ); 
break; 


case WM_DESTROY: 
PostQuitMessage( 0 ); 
break; 


default: 
bDWP = TRUE; 
break; 


} 


if( DDWP ) 
1RVal = DefWindowProc( hWnd, wMsg, wParam, lParam ); 


return 1RVal; 
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* * 
* RYG.C * 
. RYG custom-control implementation . 
* Exports: RYGWndFn . 
* * 
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#define NOCOMM 
#include <windows .h> 
#include "rygdev.h" 


/*** FUNCTION PROTOTYPES ***/ 


static void RY¥GPaint ( HWND ); 
static void RYGShowState( HDC, int, BOOL ); 
static void RYGSetMapMode( HWND, HDC ); 


/*** GLOBAL VARIABLES **+*/ 


extern HBRUSH hRYGBrush[]; 
extern DWORD dwRGB [J ; 


static int nY[3] = { 800, 250, -300 }; 
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/* defined in RYGDEV.C */ 
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* 


* RYGWndFn 


* 


* 
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LONG PASCAL FAR RYGWndFn( HWND hWnd, WORD wMsg, WORD wParam, LONG lParam ) 


{ 


HDC hDC; 
LONG 1RVal = OL; 
BOOL bDWP = FALSE; 


switch( wMsg ) 


{ 


case WM_PAINT: 
RYGPaint ( hWnd ); 
break; 


case RYG SETSTATE: 
hDC = GetDC( hWnd ); 
RYGSetMapMode( hWnd, hDC ); 


RYGShowState( hDC, SetWindowWord( hWnd, 0, wParam ), FALSE ); 


RYGShowState( hDC, wParam, TRUE ); 
ReleaseDC( hWnd, hDC ); 
break; 


case RYG GETSTATE: 
1RVal = (DWORD)GetWindowWord( hWnd, 0 ); 
break; 
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Figure 4-2. continued 


- case WM_CREATE: 
SetWindowWord( hWnd, 0, -1.); 
break; 


default: 
bDWP = TRUE; 
break; 


} 


if( bDWP ) 
1RVal = DefWindowProc( hWnd, wMsg, wParam, lParam ); 


return 1RVal; 
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* * 
* RYGPaint : 
* * 
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static void RYGPaint( HWND hWnd ) 
{ 

HDC hDC; 

PAINTSTRUCT ps; 

HBRUSH hBrush; 

int n, nState; 


hDC = BeginPaint( hWnd, &ps.); 
RYGSetMapMode( hWnd, hDC ); 


/* background */ 

hBrush = SelectObject( hDC, GetStockObject (.DKGRAY. BRUSH ) ); 
RoundRect ( hdc, -500, 1000,. 500, -1000, 250, 250 ); 
SelectObject ( hDC, hBrush ); 


/* dots. */ 
nState = GetWindowWord( hWnd, 0 ); 
for ( n=0; n<3; nt++ ) 
RYGShowState( hDC, n, (n == nState) ); 


EndPaint ( hWnd, &ps ); 


(continued) 
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Figure 4-2. continued 
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* * 
* RYGShowState s¢ 
* * 
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static void RYGShowState( HDC hDC, int nState, BOOL bColor ) 


{ 
HBRUSH hBrush; 


if( (nState < 0) {i (nState >= 3) ) 
return; 


if( bColor ) 
hBrush = SelectObject ( hDC, hRYGBrush[nState] ); 
else 
hBrush 


SelectObject ( hDC, GetStockObject ( GRAY_BRUSH ) ); 


Ellipse( hDC, -250, nY¥[nState], 250, n¥[nState]-500 ); 
SelectObject( hDC, hBrush ); 
} 
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* * 
* RYGSetMapMode * 
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static void RYGSetMapMode( HWND hWnd, HDC hDC ) 


{ 
RECT rect; 


/* set up an isotropic coordinate system centered in the client area */ 
GetClientRect( hWnd, é&rect ); 

SetMapMode( hDC, MM _ISOTROPIC ); 

SetWindowExt ( hDC, 1000, 1000 ); 

SetViewportExt ( hDC, rect.right/2, -rect.bottom/2 ); 

SetViewportOrg( hDC, rect.right/2, rect.bottom/2 ); 


(continued) 
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Figure 4-2. continued 


i 


[REE E EERE REE RARER REDE ERE REDE EERE EEE HEUER E EERE E TORE HEROS ORES ER EEE EERE EE ED 


* - * 
* RYGDEV.RC resource script * 
* * 


SHARE HEE ERE EEE EET RHEE STEERED E THEE AT ESE EETEES EERE D HEHE R ORE EERE RE HERE REED / 


#include <windows .h> 
#include "rygdev.h" 


/* icons */ 
TopLevelIcon ICON rygdev.ico 


/* menus */ 
TopLevelMenu MENU 
{ 


MENUITEM "&Red" RYG_RED 
MENUITEM "&Yellow" RYG_ YELLOW 
MENUITEM "&Green" RYG_GREEN 


} 


[PAPER ERE E EERE TREO EERE DEERE ERO EE EEE HEE E EERE EEO ESTHER RETR EH ERE REE EE ERE H ERD 


* : : * 
* RYGDEV.H eons * 
* : 8 * 


REPHEHESER HEE REESE EEE H RESET REE RHEE EES EERE F ERE R ESTEE EERE RH ER ER EES EH REE BER EH / 


#define RYG_SETSTATE (WM_USER+0) 
f#idefine RYG_GETSTATE (WM_USER#+1) 


#define RYG_RED 0 
#define RYG_YELLOW 1 
#tdefine RYG_GREEN 2 


/*** FUNCTION PROTOTYPES *+#*/ 
/* defined in RYG.C */ 
LONG PASCAL FAR RYGWndFn( HWND, WORD, WORD, LONG ); 


(continued) 
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Figure 4-2. continued 


PES HHEHEHHEEEH FREE HEE HERES HE FES HE SAH EHRHEHEHHEHES HEHEHE HEELS HER EREH THEE HE TE YH EE HE 


° * 
’ 


; RYGDEV.DEF module-definition file + 
° . * 
PPR EERE EH EEE EEE HEE HEHEHE EEE HEHEHE RHEE EHR AE EERE EEE HHH HAE THEE HE EH HEHE REE EHH 
NAME RYGDEV 
DESCRIPTION "RYGDEV.EXE version 1.0' 
EXETYPE WINDOWS 
STUB 'WINSTUB.EXE' 
CODE LOADONCALL MOVEABLE DISCARDABLE 
DATA PRELOAD MOVEABLE MULTIPLE 
SEGMENTS _TEXT PRELOAD MOVEABLE DISCARDABLE 
HEAPSIZE 1024 
STACKSIZE 5120 
EXPORTS TopLevelWndFn 
RYGWndFn 


A Custom Control in a Dynamic Link Library 


The problem with building a custom control directly into an application is that it 
is hard to use the same control in two different applications at the same time. 
You can’t simply register the same control class in two different applications be- 
cause a class definition remains valid only until you terminate the last instance 
of the application that registered the class. A second application that uses the 
class will crash if the first application terminates and the control’s window func- 
tion disappears. If you implement a custom-control class in an application and 
other applications use the class, you must devise a method to ensure that the ap- 
plication is executing, that it has registered the custom-control class, and that it 
will continue to execute until all other applications have finished using the cus- 
tom control. 


You might accomplish this through the devious use of API functions such as 
FindWindow, WinExec, and UnregisterClass, but Windows offers a more 

~ straightforward alternative: the dynamic link library. It is slightly more difficult 
to implement a custom control in a DLL than in a stand-alone application, but the 
effort is worthwhile because custom controls in DLLs can be used in multiple ap- 
plications, including resource editors such as the SDK Dialog Editor. 
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To illustrate this, compare the source code for RYG.DLL in Figure 4-3 with the 
source code for the application in Figure 4-2. Much of the source code in the ap- 
plication was copied directly into the DLL’s source code. Actions that are carried 
out during initialization, such as class registration and creation of GDI objects, 
appear in LibMain in the DLL. Similarly, the DLL’s WEP function supports ac- 
tions that are performed when the control class is no longer needed. The source 
code in RYG.C, which embodies the functionality of the control class, is used in 
the DLL just as it is in the stand-alone application. 


FARRAH HEHE EERE EERE EER HERE EERE EERE EEE EERE REE EE HH EERE EEO E EERE EEE HED ER EEE THEE 


# * 
# NMAKE description for RYG.DLL . 
# - * 


Fen EH AREER TERRE REET ER HEE EERE EERE HEHE E ERE RHEE HOE R TOE H EEE SEER EER R RE HEHEHE 


ee /c /D _WINDOWS /D _WINDLL /G2sw /Osw /W4 /Zlp $*.c 
ALL: ryg.dll 

init .obj: init.c ryg.h 

ryg.obj: ryg.c ryg.h 

wep.obj: wep.c 


ryg.dll: ryg.obj init.obj wep.obj ryg.def 
link /al:16 /nod /noe libentry init ryg wep, ryg.dll, , \ 
libw mdllcew, ryg.def 
re ryg.dll 


[FREE e RHEE EEE E HERE H EEE EERE THERE ETHER E RENNER EERE EH ES SHEESH ERE E TERED EH EE EE 


* * 
* INIT.C , 
* Initialization code for RYG.DLL . 
* * 


HORN EERE EEE E HERE HEED EEO REDE E ESET EEE EESERE HE ESTHER ESEP SR ERS DEERE ERE R EE RHEE / 


#define NOCOMM 
#include <windows.h> 
#include "gyg.h" 


Figure 4-3. (continued) 
Source code for RYG.DLL. 
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Figure 4-3. continued 


/*** GLOBAL VARIABLES *++/ 


HANDLE hDLLInst; 
HBRUSH hRYGBrush[3]; 


DWORD dwRGB[3] = { RGB(OxFF,0x00,0x00), /* red */ 
RGB (OxFF, OxFF, 0x00), /* yellow +/ 
RGB (0x00, OxFF,0x00) }; /* green */ 
static char szRYGClass[] = "RYG"; 


/*** FUNCTION PROTOTYPES ***/ 
BOOL PASCAL FAR LibMain( HANDLE, WORD, WORD, LPSTR ); 


static BOOL RegisterRYGClass( void ); 


[PEPE REE ERED EH EEE ENE EEE H EERE SEH RES DOERR DO HER EERE SEDO ORES SEER ED HEE EEE OEE RED 


* * 
* LibMain * 
* * 


HOR PE TENSE DERE E EHP E DED EEH ELE TEES ENP ORESRESHEFERES SHEDS SHO HET EERSTE HERETO HS / 


BOOL PASCAL FAR 
LibMain( HANDLE hInst, WORD wDS, WORD wHeapSize, LPSTR lpCmdTail ) 


{ 
BOOL — bRVal; 


int n; 
/* if LibEntry has called LocalInit, unlock the default data segment */ 
if( wHeapSize ) 

UnlockSegment ( wDS ); 


/* save the DLL instance handle in a global variable */ 
hDLLInst = hinst; 


/* register the custom-control class */ 
bRVal = RegisterRYGClass (); 


/* create brushes */ 
if( bRVal ) 
for( n=0; n<3; nt+.) 
hRYGBrush[n] = CreateSolidBrush( dwRGB[n] ); 


return bRVal; 


(continued) 
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Figure 4-3. continued 


[RARER EEE EERE EEE E HEHE EEE EEE EERE EEE EH EERE EEE EERE EH EEE EERE EEE HEHEHE ED 


* * 
* RegisterRYGClass * 
* * 


NEO EERE EERE EEE EERE ARENA TREE HATERS EREDRE EEE SPORE EERE R EST EER RR RRR REE Ee / 


static BOOL RegisterRYGClass () 


{ 
WNDCLASS we; 
we.lpszClassName = szRYGClass; 
we. hInstance = hDLUInst; 
we.lpfnWndProc = RYGWndFn; 
we. hCursor = LoadCursor( 0, IDC_ARROW ); 
we. hIcon = 0; 
we.lpszMenuName = NULL; 
we. hbrBackground = COLOR_WINDOW?#1 ; 
we.style = CS_GLOBALCLASS; 
we .cbhClsExtra = 0; 
we.cbWndExtra = sizeof (WORD); 
return RegisterClass( éwe ); 

} 


[RARER EERE HERE R HERRERA RE EEE ERE ERE AEE ESE E EERE EREE EEE EE EH EE EE EERE EEE EEE 


+ * 
* RYG.C Z 
* -RYG custom-control implementation d 
+ . * 
* Exports: RYGWndFn : 
* * 


HEE EREEE EEE E REET EOE E EERE EEE ER EERE EE HE REPRE EERE ETERS EERE HERE R EERE Rae / 


#define NOCOMM 

#include <windows.h> 

#include "ryg.h" 

/*** FUNCTION PROTOTYPES #**#/ 
static void RYGPaint ( HWND ); 


static void RYGShowState( HDC, int, BOOL ); 
Static void RYGSetMapMode( HWND, HDC); 


(continued) 
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Figure 4-3. continued 


/*** GLOBAL VARIABLES **+*/ 


extern HBRUSH hRYGBrush[]; /* defined in INIT.Cc */ 
extern DWORD dwRGB[]; 
static int nY[3] = { 800, 250, -300 }; 


[PERE R REE EEE EEE EEE EE EEE H HERE HERE EERE E TEER EE EE EEE REET EEE RE HERE HEHE EEE EEE 


* * 
* RYGWndFn 7 
* * 


PORE E ERE E EERE REE EERE HEHE EEE HERE H EEE EH HERE E EERE REE ER EERE EE ETRE E REE RHEE / 


LONG PASCAL FAR RYGWndFn( HWND hWnd, WORD wMsg, WORD wParam, LONG lParam ) 
{ 

HDC hdc; 

LONG 1RVal = OL; 

BOOL bDWP = FALSE; 


switch ( wMsg ) 
{ 
case WM_PAINT: 
RYGPaint( hWnd ); 
break; 


case RYG_SETSTATE: 
hDC = GetDC( hWnd ); 
RYGSetMapMode( hWnd, hDC }; 
RYGShowState( hDC, SetWindowWord( hWnd, 0, wParam ), FALSE ); 
RYGShowState( hDC, wParam, TRUE ); 
ReleaseDC( hWnd, hDC ); 
break; 


case RYG_GETSTATE: 
1RVal = (DWORD)GetWindowWord( hWnd, 0.); 
break; 


case WM_CREATE: 
SetWindowWord( hWnd, 0, -1 ); 
break; 


default: 
bDWP = TRUE; 
break; 


} 


if( -DDWP ) 
1RVal = DefWindowProc( hiind, wMsg, wParam, lParam ); 


return 1RVal; 


( continued ) 
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Figure 4-3. continued 


[PORE EERE R OEE E REDE EERE EEEEHREDEHHHEREDOREE ROME ESSROEESSOH EEE HED ETUDE EEE ROOD 


i ier an os a . 
* RYGPaint oo SEES ci ine 
* a Bget ne * 


HERE SE HEE EEE E SHOE ESHOP STEPH SES ORSEEREESEFEEFESE HS EERE SHEERS EEE RE SHEER RE OEE SH / 


static void RYGPaint ( HWND hWnd ) 
{ 

BDC hdc; 

PAINTSTRUCT ps; 

HBRUSH hBrush; 

int n, nState; 


hDC = BeginPaint( hWnd, &ps ); 
RYGSetMapMode( hWnd, hDC ); 


/* background */ 

hBrush = SelectObject( hDC, GetStockObject ( DKGRAY_BRUSH ) ); 
RoundRect ( HDC, ~500, 1000, 500, -1000,. 250, 250 ); 
SelectObject( hDC, hBrush ); 


/* dots */ 
nState = GetWindowWord( hWnd, 0 ); 
for( n=0; n<3; nt++ ) 
RYGShowState( hDC, n, (n == nState) ); 


EndPaint ( hWnd, &ps ); 
} 


[PHAR E REE TERE EE ERE HEE EE EERE EERE ERE E ERE PERE SEER EEE EEE E EEE R ER EERE ERE EES ERY 
* * 
* RYGShowState : 
* * 


HEPEE EERE E EERE EEE ER EEE REE ER TEESE ET EESEEHEEEA RETR REE H ERE HEH EERE TRH E RE REE RE | 


static void RYGShowState(. HDC hDC, int nState, BOOL bColor ) 


{ 
HBRUSH hBrush; 
if( (nState <0) ii (nState >= 3) ) 
return; 
if( bColor ) * 
hBrush = SelectObject ( ne, DI eRe veh inecece! 3 
else 
hBrush = SelectObject ( RDC, Get Stockob ject ( GRAY..BRUSH ) ); 
Ellipse (. hDC, -250, av [state]. 250, _ny[nstate] - “500 ); 
SelectObject( hDC, hBrush aha ee bes 
} Coe 
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Figure 4-3. continued 


[RRR EERE ERE E EEE R EERE EEE EERE E EEE AREER EERE EEE RE EERE EERE EERE EEE EERE EE 


* * 
* RYGSetMapMode * 
* * 


tte 


static void RYGSetMapMode( HWND hWnd, HDC hDC ) 


{ 
RECT rect; 


/* set up an isotropic coordinate system centered in the client area */ 
GetClientRect( hWnd, &rect ); 

SetMapMode( hDC, MM_ISOTROPIC ); 

SetWindowExt( hDC, 1000, 1000 ); 

SetViewportExt( hDC, rect.right/2, -rect.bottom/2 ); 

SetViewportOrg( hDC, rect.right/2, rect.bottom/2 ); 


[RARER H EEE EERE REET EE EERE AEE EPR EEE TERETE EEE E ETHER ER EEE EERE EEE REE He 


* * 
* WEP .C . 
* Windows exit procedure for RYG.DLL * 
* * 
* Exports: WEP RESIDENTNAME . 
* * 


PERE EE ETE EERE RHEE RETR EEE EEE REESE EEE E HER ERE EE EERE EERO REE ER RE Ee | 


#define NOCOMM 
#include <windows.h> 


/*** GLOBAL VARIABLES +***/ 


extern HBRUSH hRYGBrush[]; ; /* defined in RYG.C */ 


ay 
[PERE E EERE EERE EERE HEHE EEE EEE EERE EERE HERE EERE EEE HERE RETR REET ERE EEE REE 


* * 
* WEP * 
* * 


EEE EERE EERE EERE EERE AEE EEE AREER EEE EE EERE HESS ERE REE REESE REE EERE RE REE EE / 


int PASCAL FAR WEP( int nParam ) 
{ 


int n; 


(continued) 
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Figure 4-3. continued 
/* destroy brushes */ 


for(. n=0; n<3; nt++ ) 
DeleteObject ( hRYGBrush[n] ); 


return 1; 


[REFEREE ORE EEE EEE ERE E EES HE REE EEE ETE EERE SEER ETTORE EE EE HEED EEE ER HER EEE EEE EHD 


* + 
* RYG.H * 
* Header file for RYG.DLL * 


FEHR EERE REE E EE EET EEE EERE E PEPE E HERO E ORES HERA EH EERE RESET ERE R EERE ERE AES / 


#define RYG_SETSTATE (WM_USER+0) 
#define RYG_GETSTATE (WM_USER+1) 


#tidefine RYG_RED 0 
#define RYG_YELLOW 1 
#define RYG_GREEN 2 


/*** FUNCTION PROTOTYPES ***/ 


/* defined in RYG.C */ 
LONG PASCAL FAR RYGWndFn( HWND, WORD, WORD, LONG ); 


PPA EEH EER EE HSER EEE EE EESEEEEEER SEES HE EREHEREEEEEREEES HR EH ENERO HHHA EHH HEHE SE HM 


. 3 RYG.DEF module-definition file * 


* 
cf 


PRFHAAE EERE REET EREEE HERES HE ERE SEH EERE EE REE EERE EEE ESSERE AER EEEREET OTE REESE HEE 


LIBRARY RYG 

DESCRIPTION "RYG version 1.0' 

STUB 'WINSTUB.EXE' 

EXETYPE WINDOWS 

CODE LOADONCALL MOVEABLE DISCARDABLE 
DATA PRELOAD MOVEABLE SINGLE 
HEAPSIZE 0 


(continued) 
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Figure 4-3. continued 


SEGMENTS INIT_TEXT PRELOAD DISCARDABLE 
WEP_TEXT PRELOAD FIXED 

EXPORTS WEP @1 RESIDENTNAME 
RYGWndFn 


Although RYG.DLL is small, it contains all four of the essential elements of a 
dynamic link library that supports a custom-control class: 


m An initialization function ibMain) 

m A call to RegisterClass to register the control class 
m@ A control-class window function 

@ An exit procedure (WEP) 


Each of these components of the DLL’s structure corresponds to a part of the ap- 
plication in which the custom-control class was originally developed. 


DLL Initialization and Class Registration 


A DLI’s initialization function, LibMain, is the best place to call RegisterClass for 
a custom-control class. When you do this, you can be certain that RegisterClass 
will be called exactly once when Windows loads the library. In a DLL, a custom- 
control class should be registered with the CS_GLOBALCLASS style. This style 
makes the class registration available to all applications, not just the application 
that first loads the DLL. 


The Control Class Window Function 


It goes without saying that the window function that supports a custom-control 
class is always part of a custom-control DLL. If you develop a custom control by 
embedding it in an application, you can often transplant the window-function 
source code directly into the DLL. 


The Windows Exit Procedure (WEP) 


You should implement and export the WEP function in a custom-control library 
just as you would in any other DLL. Windows calls the WEP function when the 
DLL is no longer to be used, before it discards the library from memory. 


The purpose of including WEP in a library is to provide a consistent method for 
library routines to clean up at the time the library is unloaded. In the case of 
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RYG.DLL, the WEP routine deletes the GDI objects that the RYG class uses to 
paint the control. You might also think that WEP would be a reasonable place to 
call UnregisterClass to unregister the custom-control class, but don’t do it. Win- 
dows implicitly unregisters all classes that have been registered in a module at 
the time the last instance of the module is unloaded. Calling UnregisterClass in a 
DLL's WEP function is redundant. 


Using a Custom Control 


As it stands, RYG.DLL supports a usable custom-control class named RYG. To 
create RYG controls, an application first loads RYG.DLL. It can do this explicitly 
by calling LoadLibrary in its WinMain function: 


hLibrary = LoadLibrary( "RYG.DLL" ); 


An application can also load the library implicitly by importing a library func- 
tion. A simple way to do this is to include an appropriate IMPORTS statement in 
the application’s module-definition file: 


IMPORTS RYG.WEP 


After the library has been loaded, the application can create RYG controls di- 
rectly by calling CreateWindow or indirectly through CONTROL statements in 
DIALOG resources in its .RC file. 


The most important drawback to RYG.DLL is that a resource editor such as the 
SDK Dialog Editor, DIALOG.EXE, does not recognize the RYG control class. This 

_ makes it harder than it ought to be to design an application that uses RYG con- 
trols. You need to do some extra work to make a custom-control class known to 
a resource editor, but the payoff is a custom-control class that can be used within 
the editor just like one of the predefined Windows control classes. 


Custom Controls and the Dialog Editor 


The Windows SDK documentation describes the three interface functions that a 
resource editor can call to determine the characteristics of a custom-control class 
in a DLL. You should build these functions into a custom-control DLL to give 
resource editors such as the SDK Dialog Editor the ability to manipulate the cus- 
tom control. (Other resource editors might use a different method to communi- 
cate with a custom-control DLL. See the documentation for your resource edito 

for details.) | 
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The three resource-editor interface functions described in the Windows SDK are 
listed in Figure 4-4. The Info function lets a resource editor determine which 
custom-control styles are available and which style to use by default. The Style 
function provides a way for a resource editor to invoke a dialog box through 
which the user can specify the style of a particular custom control. The Flags 
function associates a string of symbolic names with a particular control’s style. 


Name Export Ordinal Notes 


Info Z Returns descriptive data about the control 
library to a resource editor in a CTLINFO 
data structure. 


Style 3 Updates a CTLSTYLE data structure con- 
taining a style description for a particular 
control. 

Flags 4 Builds a string of symbolic style names for 
inclusion in a CONTROL statement in a 
RC or .DLG file. 

Figure 4-4. 


Resource-editor interface functions in a custom-control DLL. 


A resource editor identifies the interface functions in a custom-control library by 
reference to the export ordinal numbers you assign. Although you must use the 
predefined ordinal values, you can choose any convenient names for these func- 
tions. It’s good practice, though, to use names derived from the name of your 
custom control. 


Because this interface relies on ordinal numbers to identify the resource-editor 
entry points in a library, you can define entry points for only one custom-control 
class per DLL. If you want to use several different custom controls in a resource 
editor, you may need to define each custom-control class in a separate DLL. The 
alternative is to define different controls as different styles in the same control 
class. The predefined static and button classes adopt this approach—the pre- 
defined static class includes, among others, static text, rectangle, and frame 
styles; the button class includes push buttons, check boxes, radio buttons, and 
group boxes. . 


A typical DLL interface to the Windows SDK Dialog Editor is illustrated in the 
source code in Figure 4-5 on the following page, which implements a custom- 
control library named COLORCTL.DLL. The custom-control class supported in 
COLORCTL.DLL is named ColorCtl. The purpose of the ColorCtl control is to fill 
its window rectangle with color. You set the control’s color by specifying an RGB 
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value as the control’s window text. The control’s style determines whether the 
displayed shape is a rectangle, an ellipse, or a round-cornered rectangle and 
whether the control is displayed with a border. Several examples of ColorCtl 


controls are shown in Figure 4-6 on page 125. 


FOC eH EOE EERE E EHH OEE EEE EERE TETHER ERS HEH PRES ER ER OH HE EEE OEEEREE FERRER EERE OY 


# 


# NMAKE description for COLORCTL.DLL 


# 


* 


* 


FAP eee Hee ee HERR HE EEE HT EP E HERE ERE EEHHEEEER ERS SEEHEEREEOESER REDD ESHER EEE ED 


.C.0bj: 


cl /AMw /c /D _WINDOWS /D _WINDLL /G2sw /Osw /W4 /Zlp $*.c 


ALL: 
colorctl.obj: 
digedit .obj: 
init .obj: 
wep.obj: 


colorctl res: 


colorctl.dll 
colorctl.c colorctl.h 
digedit.c colorctl.h 
init.c golorctl:h 


wep.c 


colorctl.re colorctl.h 


re. /r colorctl.re 


colorctl.dll: colorctl.obj digedit .obj init.obj wep.obj \ 
colorctl.res colorctl.def 
link /al:16 /nod /noe libentry init colorctl dlgedit wep, \ 


colorctl.dll, , libw mdllicew, colorct 


re colorctl.res colorctl.dil 


[HORE E RHE TE RHEE RESO REEF EHR ES ES OH EPEH EEE THERE EEE HER FER PE ETE HHEES OEP ER SHER EEE EO 


* 


* INIT.C 


* Initialization for COLORCTL.DLL 


+ 


* 


* 


ote 


PHEEEEH HERETO EEE THREES EERE TREE REEF EE EES TOES HEHE EH EE TERS OH EEE HERE RS EH EERE He / 


‘#define NOCOMM 


#include <windows . h> 
#include "colorctl.h" 


Figure 4-5. 


Source code for COLORCTL.DLL. 
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Figure 4-5. continued 
/*** GLOBAL VARIABLES ***/ 
HANDLE hDLLInst; 
static char szColorCtlClass[] = COLORCTLCLASSNAME; 
/*** FUNCTION PROTOTYPES *#**/ 
BOOL PASCAL FAR LibMain( HANDLE, WORD, WORD, LPSTR ); 


static BOOL RegisterColorCtlClass( void ); 


[REE REE EEN R EEE ER EEE EEN ESE EEE SORE EERE RE ER OEE E EEE HEHEHE HEE ERERE EEO DE 


* * 
* LibMain * 
* * 


HEHAEHH ETE ETE REE HEREE HERES ETERS EEE EERE E HEHEHE TEES ERE HEHEHE DERE ORES TEE EE / 


BOOL PASCAL FAR 

LibMain( HANDLE hInst, WORD wDS, WORD wHeapSize, LPSTR lpCmdTail ) 

{ 
/* if LibEntry has called LocalInit, unlock the default data segment */ 
if( wHeapSize ) 
UnlockSegment ( wDS ); 


/* save the DLL instance handle in a global variable +/ 
hDLLInst = hInst; 


/* register the custom-control class */ 
return RegisterColorCtlClass (); 


[RARER TERRE EE EEE EERE EH EH EEE TAREE TREE EEE EEE EH ED ERATE HEHE ERE EERE ED ERE RED EEE DE 
* * 
* RegisterColorCtlClass * 
* + 


HHEEEE HERES HERR ER THERE RHEE EERE EERE ERE R EEE E REESE RHEE RHEE TREO HERR EHR R REE ERE / 


static BOOL RegisterColorCtlClass () 


{ 
WNDCLASS = we; 


we. lpszClassName = szColorCtlClass; 


we. hinstance = hDLLInst; 

we.lpfnWndProc = = ColorCtlWndFn; 

we. hCursor = LoadCursor( 0, IDC_ARROW ); 
we. hIcon = 0; 

we. lpszMenuName = NULL; 


(continued) 
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Figure 4-5. continued 


we .hbrBackground = 0; 


we.style = CS DBLCLKS |. CS_GLOBALCLASS; 
wo.cbClsExtra = 0; 
we.cbWndExtra = 0; 


return RegisterClass( &éwe ); 


[PEPE E EER ERROR EEE THREE TEER REEL EEE REE EEE RETR HE RETR E REE EERE EEE EE EERE EH EE 


* : * 
* COLORCTL.C : 
* Implementation of the ColorCtl control * 
* * 
* Exports: ColorCtlWndFn * 
* * 


REN EREEER ERE ER EEE HERE EEE EERSTE AEE E TEER ES ERE REE H EH EEE ERE EEEEE EERE E REE HEHE R ENE | 


#define NOCOMM 


#include <windows .h> ae 
#include <stdlib.h> /* strtoul */ 
#include "colorctl.h" 


/*** FUNCTION PROTOTYPES **+/ 


static void MsgPaint( HWND ); . 
static BOOL MsgEraseBkgnd( HWND, HDC ); 


[REPRE EEE E ERE O EERE EERE TENE REFERER ESSER EES SEP EEE SEER EEE REET HERE EERE REESE EE ETE 


+ , * 


* ColorCtlWndFn * 
* * 


REREHEEE EERE EERE ERE RETR EERE NEE EERE REET EERE REESE EERE EERE ERR ORR R ER EER EE | 


LONG PASCAL FAR 
ColorCtlWndFn( HWND hiind, WORD wMsg, WORD wParam, LONG 1Param ) 
{ 

LONG iRVal = OL; 

BOOL bDWP = FALSE; 


-switch( wMsg ) 
A 
case WM_PAINT: 
MsgPaint( hWnd ); 
break; 


(continued) 
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Figure 4-5. continued 


} 


case WM_NCPAINT: /* don't paint the default border */ 
case WM_NCCALCSIZE: 
break; 


case WM_ERASEBKGND: 
1RVal = MsgEraseBkgnd( hWnd, wParam )j; 
break; 


default: 
bDWP = TRUE; 
break; 


} 


if( bDWP ) 
1RVal = DefWindowProc( hWnd, wMsg, wParam, lParam ); 


return 1RVal; 


Y AX hokehehoehaheluhehehcheleiahehetehetataleheheieteheiehehehetiheheieielelehehstelietettekehoheheheteiebeiehetsehehehetiteieietelelelststeleieletehelel 


* 


* MsgPaint * 


* 


* 
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static void MsgPaint( HWND hWnd ) 


{ 


DWORD dwStyle; 
DWORD dwRGB ; 
char szRGB(12]; 
HDC hDC; 
PAINTSTRUCT ps; 

RECT rect; 
HPEN hPen; 
HBRUSH hBrush; 
int nCorner; 


hDC = BeginPaint( hWnd, &éps ); 

/* get the style flags and color */ 

dwStyle = GetWindowLong( hWnd, GWL_STYLE ); 
GetWindowText ( hWnd, szRGB, sizeof szRGB ); 
dwRGB = HexToDWord( szRGB ); 

/* get the client-area rectangle */ 
GetClientRect ( hWnd, Srect ); 
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/* select pen and brush */ 
hBrush = CreateSolidBrush( dwRGB ); 
hBrush = SelectObject( hDC, hBrush ); 


if( dwStyle & WS_BORDER ) 
hPen = GetStockObject ( BLACK_PEN ); 
else 
{ 
hPen = GetStockObject ( NULL_PEN ); 
InflateRect ( &rect, 
GetSystemMetrics( SM_CXBORDER ), 
GetSystemMetrics ( SM_CYBORDER ) ); 


} 
hPen = SelectObject( hDC, hPen ); 


/* the control's style determines its shape */ 
switch( dwStyle & (CCS_RECT | CCS_ROUND) ) 
{ 
case CCS_ROUND: 
Ellipse( hDc, 0, 0, rect.right, rect.bottom ); 
break; eek 


case. (CCS_RECT {| CCS_ROUND): . 
nCorner = MulDiv( min( rect.right, rect.bottom ), 2, 3°); 
RoundRect ( hDC, 0, 0, rect.right, rect.bottom, nCorner, nCorner ); 
break; 


case CCS_RECT: 
default: 
Rectangle({ hDC, rect.left, rect.top, rect.right, rect.bottom ); 
break; : 
} 


hPen = SelectObject( hDC, hPen ); 
hBrush = SelectObject( hDC, hBrush ); 
DeleteObject ( hBrush ); 


EndPaint ( hWnd, &ps ); 
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* MsgEraseBkgnd * 
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static BOOL MsgEraseBkgnd( HWND hWnd, HDC hDC ) 


{ 
HBRUSH hBrush; 
RECT rect; 
hBrush = (HBRUSH) SendMessage( GetParent ( hWnd ), 
WM_CTLCOLOR, 
hdc, : 
MAKELONG (hWnd, CTLCOLOR_STATIC) ); 
GetClientRect( hWnd, &rect ); 
FillRect( hDC, &rect, hBrush ); 
return TRUE; 
} 
[PHAR E REET OEE REESE REEF OREO TEEPE RE RHO EEESE EES EPE SEE ESSE EERE REET TERETE EDD 
* * 
* HexToDWord * 
* Converts a hexadecimal ASCIIZ string to a DWORD. * 
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DWORD PASCAL FAR HexToDWord( LPSTR pHex ) 


{ 
LOCALHANDLE hBuf; 
NPSTR pBuf; 
static NPSTR pEnd; 
DWORD ' dwRVal; 


if( (NULL != pHex) && *pHex ) 
{ 
/* allocate a temporary buffer in the DLL's local heap */ 
hBuf = LocalAlloc( LHND, lstrlen( pHex ) +1 ); 
pBuf = LocalLock( hBuf ); 
lstrepy( pBuf, pHex ); 


/* convert the string */ 
dwRVal = strtoul( pBuf, &pEnd, 16); 
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/* if non-hexadecimal string, return a default RGB value */ 
if( *pEnd ) 
GwRVal = DEFRGB; 


/* free the buffer */ 
LocalUnlock( hBuf ); 


LocalFree( hBuf ); 
} 


else 
dwRVal = DEFRGB; 


return dwRVal; 


[PEER R REE EEE E EHR E EERE HERE E EERE EEE EEE EERE ERE A EERE EERE HSER EER EHR EHH EERE RHEE EEE 


* DLGEDIT.C ; . 
* Entry points for Windows dialog editor for the ColorCtl control * 
* * 
* Exports: ColorCtlinfo i 
* ColorCtl1Style * 
7 ColorCtlFlags , 
. ColorCt1DlgFn : 
* * 


HERE HE EERE RESTS E REET H EEE E TEETER TEER EEE R EERE TERE EERE E EE HEE EER HERR ERE E RHEE ES / 


#define NOCOMM 

#include <windows.h> 

#include <custentl .h> 

#include <string.h> /* _fmemcpy */ 
#include "colorctl.h" 


/*** GLOBAL VARIABLES ***/ 


extern HANDLE hDLLInst; /* defined in INIT.C */ 
static LPFNSTRTOID pStrTolIdFn; 
static LPFNIDTOSTR pldToStrFn; 


static CTLINFO Ctlinfo = 


{ 
0x0100, /*-wVersion */ 


3, /* wCtlTypes */ 
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COLORCTLCLASSNAME, /* szClass */ 
we /* szTitle */ 
te /* szReserved */ 


0, 40, 20, CCS_RECT | WS_CHILD i WS_VISIBLE, 
"ColorCtl (rect)", 

0, 30, 30, CCS_ROUND | WS_CHILD | WS_VISIBLE, 
"ColorCtl (round) ", 

0, 40, 20, CCS_ROUND | CCS_RECT | WS_CHILD { WS_VISIBLE, 
"ColorCtl (round rect)" 

}; 


static struct /* dialog control IDs */ 
{ 
WORD wiDScroli; 
WORD wIDEdit; 
} 
CtiRGB[] = { { IDRED, IDREDIT }, 
{ IDGREEN, IDGEDIT }, 
{ IDBLUE, IDBEDIT } }; 


static struct /* user-defined styles */ 
{ 
WORD wFlag; 
char szName[16]; 
} 
UserStyle[] = { { CCS_RECT, "CCS_RECT" }, 
{ CCS_ROUND, "CCS_ROUND" } }; 


/*** FUNCTION PROTOTYPES +#*+/ 
GLOBALHANDLE PASCAL FAR ColorCtlinfo( void ); 


GLOBALHANDLE PASCAL FAR ColorCtlStyle( HWND, GLOBALHANDLE, 
LPFNSTRTOID, LPFNIDTOSTR ); 


int PASCAL FAR ColorCtlFlags( WORD, LPSTR, WORD ); 

BOOL. PASCAL FAR ColorCt1lDlgFn(.HWND, WORD, WORD, LONG ); 
static void MsgCommand( HWND, GLOBALHANDLE, WORD, LONG ); 
static void MsgClicked( HWND, WORD ); 

static void MsgHScroll( HWND, WORD, LONG ); 

static void RedisplaySampleColor( HWND ); 

static void SetStyleInfo( HWND, LPCTLSTYLE ); 

static void GetStyleInfo( HWND, LPCTLSTYLE ); 
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* ColorCtlInfo * 


? * 
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GLOBALHANDLE PASCAL FAR ColorCtlinfo() 


{ 
GLOBALHANDLE  §hCtlinfo; 


LPCTLINFO :lpCtlinfo; 
hCtlInfo = GlobalAlloc( GHND, (DWORD)sizeof(CTLINFO) ); 


if( hCtlInfo ) 


{ 
lpCtlInfo = (LPCTLINFO)GlobalLock( hCtlinfo ); 


_fmemcpy( lpCtlinfo, &CtlInfo, sizeof(CTLINFO) ); 
GlobalUnlock( hCtlInfo ); 
} ; 


return hCtlinfo; 
} 


[PEER RRO RHEE EERE RENEE RE HERE EERE EERE EERE EERE E ERE EERE EERE RHEE EEE HEH EEE 


* ColorCtlStyle * 
* * 
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-GLOBALHANDLE PASCAL FAR 
ColorCtiStyle( HWND hWnd, GLOBALHANDLE hCtlStyle, 
LPFNSTRTOID IpfnStrToId, LPFNIDTOSTR lpfniIdToStr ) 


{ 
int nRVal; 


/* save callback function addresses +/ 
pStrToIdFn = lpfnStrTofd; 
pidToStrFn = lpfnidToStr; 


/* display the style dialog box */ 
nRVal = DialogBoxParam( hDLLInst, 
: "ColorCtlStyleD1g", 
hWnd, 
ColorCtlDlgFn, 
MAKELONG (hCtiStyle, 0). ); 


return nRVal; 
(continued) 
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* * 


* ColorCtlFlags 7 


* * 
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int PASCAL FAR ColorCtlFlags( WORD wFlags, LPSTR pString, WORD wMaxLen ) 
{ 


int n; 


/* start with a null string */ 
pString[0] = 0; 


/* copy flag string for each user style */ 
for( n=0; n<ARRN(UserStyle); nt+ ) 
if( wFlags & UserStyle[n] .wFlag ) 
{ 
if( *pString ) 
istrcat( pString, "i" ); /* append a separator */ 


lstrceat( pString, UserStyle[n] .szName ); 
} 


/* return the total string length */ 
return lstrlen( pString ); 


} 


[ARERR EERE EERE EE EARTH EERE RHEE EERE EER ER EEE REET EEE ER EEE H EERE ER EH EET HEE EEE OH 
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* * 


* ColorCt1DlgFn - 
* . # 
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BOOL PASCAL FAR 
ColorCtlDigFn( HWND hDlg, WORD wMsg, WORD wParam, LONG lParam ) 
{ 

static GLOBALHANDLE hCtlStyle; 

LPCTLSTYLE lpCtlStyle; 

BOOL bRVal = TRUE; 


switch ( wMsg ) 
{ 
case WM_INITDIALOG: 
hCtlStyle =. LOWORD (lParam) ; 
ipCtlsStyle = (LPCTLSTYLE)GlobalLock( hCtl1Style ); 
SetStyleInfo( hDlg, lpCtlStyle ); 
GlobalUnlock( hCtlStyle ); 
break; 
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} 


ca 


se WM_COMMAND: 


MsgCommand({ hDig, hCtlstyle, wParam, 1Param ); 
break; 


ca 


se WM_HSCROLL: 


MsgHScroll( hDlg, wParam, 1Param ); 
break; 


de 


fault: 


bDRVal = FALSE; 
break; 


} 


retu 


rn bRVal; 


[REPRE EEE EE ERE EERE EEE ERE ORE E EERE HERE REE H EERE HERE EEE DEERE EOE REET E EE HEHE H 


* 


* MsgCommand 


* Notes: 

* IDREDIT = (IDRED+1000) 

* IDGEDIT = (IDGREEN+1000) 
* IDBEDIT = (IDBLUE+1000) 


FORE EE HEED EOE THEE EERE OE HES HOES ETOH EE ESEE PERSE ESHEETS EOE EE SON HEE T ORE E ERED / 


static void 
MsgCommand( HWND hDlg, GLOBALHANDLE hCtlStyle, WORD wParam, LONG lParam ) 


{ 


LPCTLSTYLE l1pctlstyle; 


DWORD dwRVal; 
char szID[20]; 
HWND hCtl; 
int n; 
switch( wParam ) 
{ 

case IDOK: 


/* verify the control ID */ 
GetDigItemText ( hDlg, IDID, szID, sizeof szID ); 
dwRVal = (*pStrToIdFn) ( szID ); 


/* if the control ID is valid, end the dialog */ 
if (- LOWORD (dwRVal).) : 
{ 


lpCtlstyle = bakes eu ); 
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lpCtlStyle->wId = HIWORD (dwRVal) ; 
GetStyleInfo( hDlg, lpCtlStyle ); 


GlobalUnlock( hCtlStyle ); 


EndDialog( hDlg, TRUE ); 
} 


else 
PostMessage( hDlg, 
WM_NEXTDLGCTL, 
GetDigItem( hDlg, IDID ), 
(LONG) TRUE ); 
break; 


case IDCANCEL: 
EndDialog( hDlg, FALSE ); 
break; 


case IDREDIT: 
case IDGEDIT: 
case IDBEDIT: 
if( EN_KILLFOCUS == HIWORD(lParam) ) 
{ 
/* verify the new color value */ 
n = GetDlgItemInt( hDlg, wParam, NULL, FALSE ); 
if( nm > MAXCVAL ) 
{ 
n = MAXCVAL; 


SetDligItemIint( hDlg, wParam, MAXCVAL, FALSE }); 


} 


/* update the corresponding scroll bar */ 
hCtl = GetDlgItem( hDlg, wParam-1000 ); 
SetScrollPos( hCtl, SB.CTL, n, TRUE ); 


RedisplaySampleColor( hDlg ); 
} 


break; 


case IDBORDER: 
case IDRECT: 
case IDROUND: 
if( BN_CLICKED == HIWORD (lParam) _) 
MsgClicked( hDlg, wParam ); 
break; 
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} 


default: 
break; 


[PRE R ERE EEE R EEE H HERETO REE EOE EERE THEE HEHE EERE ERE EERE REE SHEE ER HERE RE EHH ERO EEE 


* 


* MsgClicked 
* 


* 


* 
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static void MsgClicked( HWND hDlg, WORD wParam ) 


{ 


HWND hCtl; 
DWORD dwStyle, dwFlag; 


/* determine which style flag to update */ 
switch( wParam ) 
{ 
case IDBORDER: 
dwFlag = WS_BORDER; 
break; 


case IDRECT: 
dwFlag = CCS_RECT; 
break; 


case .IDROUND: 
dwFlag = CCS_ROUND; 
break; 


} 


/* update the control style */ 
hCtl = GetDlgItem( hDlg, IDCC ); 
dwStyle = GetWindowLong( hCtl, GWL_STYLE ); 


if( IsDlgButtonChecked( hDlg, wParam ) ) 
dwStyle i= dwFlag; : 


else 


dwStyle &= ~dwFlag; 


SetWindowLong( hCtl, GWL_STYLE, dwStyle ); 


/* redisplay the sample */ 
InvalidateRect ( hCtl, NULL, TRUE ); 
UpdateWindow( hCtl ); 
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[HERRERA EERE HE ERED ERERESEEEEOO REEDS EEEHO OEE SHH EEEE SHEER HH EERED EO ER ES OEE 
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* MsgHScroll 
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static void MsgHScroll( HWND hDlg, WORD wParam, LONG lParam ) 


{ 


int nPos; 
BOOL bUpdate = TRUE; 


/* compute a new scroll-bar thumb position */ 
nPos = GetScrollPos( HIWORD(1Param), SB_CTL ); 


switch( wParam ) 


{ 


case SB_TOP: 
nPos = 0; 
break; 


case SB_ BOTTOM: 
nPos = MAXCVAL; 
break; 


case SB_LINEUP: 
if( nPos >.0 ) 
~-nPos; 
break; 


case SB_LINEDOWN: 
if( nPos < MAXCVAL ) 
++nPos; 
break; 


case SB_PAGEUP: 
nPos = max( 0, nPos-0x10 ); 
break; 


case SB_PAGEDOWN: 


nPos = min( MAXCVAL, nPost0x10 );_ 


break; 
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case SB.THUMBPOSITION: 
case SB.THUMBTRACK: 
nPos = LOWORD (lParam) ; 
break; 


default: 
bUpdate = FALSE; 
break; 


} 


/* update the ScrollBar, Edit, and ColorCtl controls */ 
if( bUpdate ) 
{ 
SetScrollPos( HIWORD(1Param), SB_CTL, nPos, TRUE ); 
SetDlgitemInt ( hDlg, 1000+GetDlgCtrlID( HIWORD(1Param) ), 
nPos, FALSE ); 
RedisplaySampleColor( hDlg ); 


| hel hiatohlehtchelehehlahdahsidehichebhetdatalabcleheledstchetelettak ide datdtehdehtdtdehdttbedatth thd tikka tbtdeted 
ee: * 
* RedisplaySampleColor . 
* 7 * 
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static void RedisplaySampleColor( HWND hDlg ) 


{ 
BYTE cValue [3]; 
char szRGB [12]; 
HWND hCt1; 
int ni 
for (: n=0; n<3; nt++ ) 
cValue[n] = (BYTE)GetDlgItemInt ( hDlg, Ct1RGB[n] .wIDEdit, 
NULL, FALSE ); 
wsprintf( szRGB, "0x%061X", RGB(cValue[0], cValue[1], cValue[2]) ); 
hCtl = GetDlgItem( hDig, IDCC ); 
SetWindowText ( hCtl,.szRGB ); 
InvalidateRect( hCtl, NULL, FALSE ); 
UpdateWindow( hCtl ); 
} 
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* SetStyleInfo * 


a 
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static void SetStyleInfo( HWND hDlg, LPCTLSTYLE lpCtlStyle ) 


{ 


char szID[(20]; 
DWORD GwRGB; 
BYTE ceValue [3]; 
HWND hCtl; 

int n; 


/* display the ID value */ 
(*pIdToStrFn) ( lpCtiStyle->wId, szID, sizeof szID ); 
SetDlgItemText ( hDlg, IDID, szID ); 


/* get the RGB color value from the window text */ 
if( lstrcempi( lpCtlStyle->szTitle, "Text" ) ) 
dwRGB = HexToDWord( lpCtlstyle->szTitle ); 
else 
dwRGB = DEFRGB; 


cValue[0] = GetRValue (dwRGB) ; 
eValue[1] GetGValue (dwRGB) ; 
cValue [2] GetBValue (dwRGB) ; 


/* set the scroll bars and edit controls */ 

for( n=0; n<3; n++ ) 

{ 
hCtl = GetDlgItem( hDlg, Ct1RGB[n].wIDScroll ); 
SetScrollRange( hCtl, SB_CTL, 0, MAXCVAL, TRUE ); 
SetScrollPos( hCtl, SB_CTL, cValue[n], TRUE ); 


SetDlgItemInt( hDlg, CtlRGB[n] .wIDEdit, cValue[n], FALSE ); 
} 


/* display the style check boxes */ 
CheckDlgButton( hDlg, IDBORDER, 

(WS_BORDER == (1pCtlStyle->dwStyle & WS_BORDER)) ); 
CheckDlgButton( hDlg, IDRECT, 

(CCS_RECT == ( (WORD) lpCtlStyle->dwStyle & CCS_RECT)) ); 
CheckDlgButton( hDlg, IDROUND, 

(CCS_ROUND == ((WORD) lpCtiStyle->dwStyle & CCS_ROUND)) ); 


(continued) 


121 


Windows: Developer’s Workshop 


Figure 4-5. continued 


/* display the sample control +*/ 
hCtl = GetDlgItem( hDlg, IDCC ); 


SetWindowLong( hCtl, GWL_STYLE, lpCtlStyle->dwStyle ); 
SetWindowText ( hCtl, lpCtlStyle->szTitle ); 


[HARPER EERE HER EEREHEREHERESE SAREE EHR R EEE RER ERE HERE HE REE HEE RED ER ERE H HERE DE HD 

* * 
+ 

* GetStyleInfo * 

* * 
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static void GetStyleInfo( HWND hDlg, LPCTLSTYLE lpctlStyle ) 
{ 

BYTE cValue [3]; 

DWORD dwRGB; 

int n; 


/* get the color values from the edit controls */ 
for(-n=0; n<3; nt+.) 
cValue[n] = 
(BYTE) GetDigitemint ( nDlg, Ct1RGB[n} . wIDEdit, NULL, FALSE de 
dwRGB = RGB(cValue[0], cValue[1], cValue[2] ); 


/* use the RGB value as the window text */ 
wsprintf( lpCtlStyle->szTitle, "0x%061X", dwRGB ); 


/* update the style flags */ 


lpCtlStyle->dwStyle = 
GetWindowLong ( GetDigItem ( hDlg, IDCC ), GWL_STYLE ); 


[PARA ERR H HERES R ERE THEE EEE EERE EE HHR ETHER ER EEE RER EERE ETH EE EEE OR ERE SER ER ESE REED 


‘ * * 
* WEP..C if 
* Windows exit procedure for COLORCTL.DLL * 

Oe : eign 
* Exports: WEP RESIDENTNAME * 
* * 


REEEHEROEHO REESE EEE EHER EOP HELE HEE REEF HREEHHEREEHH ERE ES EH REEF ERROR HERES HHH EE / 


#define NOCOMM 
#include —- <windows.h> 
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* * 
* WEP * 
* * 
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int PASCAL FAR WEP( int nParam ) 


return 1; 
} 
[ARAN REE E EERE REE EEE EERE EE OEE THERE ETHER EEE HERE ES EERE H THERE HOHE THERE RE HEE EEE 
* * 
* COLORCTL.RC resource script * 
* + 


HERE HEHE SEHR EERE EEE TREE E HERE REEEEE SORE EERE E REE HERE E THREE EHH REE ERE EE / 


#include <windows .h> 
#include "colorctl.h" 


ColorCtlStyleDlg DIALOG LOADONCALL MOVEABLE DISCARDABLE 18, 30, 242, 102 
CAPTION "ColorCtl Control Style ..." 
STYLE WS CAPTION {| WS_POPUP 
{ 
CONTROL "&ID:", 0, "Static", SS_RIGHT { WS_CHILD, 4, 6, 12, 8 
CONTROL "", IDID, "Edit", ES_LEFT |: ES_UPPERCASE : WS_BORDER 
i WS_TABSTOP | WS_CHILD, 20, 4, 76, 12 
CONTROL "", IDCC, "ColorCt1", CCS_RECT | WS CHILD, 194, 4, 40, 18 
CONTROL "Color", 0, "Button", BS_GROUPBOX ; WS_CHILD, 2, 16, 182, 64 
CONTROL "&Red", 0, "Static", SS_LEFT : WS_CHILD, 6, 30, 24, 8 
CONTROL "", IDRED, "ScrollBar", SBS_HORZ i WS_TABSTOP | WS_CHILD, 
32, 29, 128, 10 
CONTROL "", IDREDIT, "Edit", ES_LEFT | WS_BORDER | WS_TABSTOP {| WS_CHILD, 
162, 28, 18, 12 
CONTROL "&Green", 0, "Static", SS_LEFT | WS CHILD, 6, 46, 24, 8 
CONTROL "", IDGREEN, "ScrollBar", SBS_HORZ | WS_TABSTOP i WS_CHILD, 
32, 45, 128, 10 
CONTROL "", IDGEDIT, "Edit", ES_LEFT : WS_BORDER : WS_TABSTOP ; WS_CHILD, 
162, 44, 18, 12 
CONTROL "G&Blue", 0, “Static", SS_LEFT i WS_CHILD, 6, 62, 24, 8 
CONTROL "", IDBLUE, “ScrollBar", SBS_HORZ | WS_TABSTOP } WS_CHILD, 
32, 61, 128, 10 . 
CONTROL "", IDBEDIT, "Edit", ES_LEFT | WS_BORDER } WS_TABSTOP | WS_CHILD, 
162, 60, 18, 12 
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} 


CONTROL "Style", 0, "Button", BS_GROUPBOX |} WS_CHILD, 187, 27, 52, 54 
CONTROL "Bsorder", IDBORDER, "Button", BS_AUTOCHECKBOX | WS_TABSTOP 
| WS_CHILD, 190, 36, 48, 12 
CONTROL "Réect", IDRECT, "Button", BS_AUTOCHECKBOX ! WS_TABSTOP 
| WS_CHILD, 190, 48, 48, 12 
CONTROL "Rouénd", IDROUND, "Button", BS _AUTOCHECKBOX | WS_TABSTOP 
| WS_CHILD, 190, 60, 48, 12 
CONTROL "Ok", IDOK, "Button", BS_DEFPUSHBUTTON i WS.TABSTOP 
! WS_CHILD, 86, 84, 32, 14 
CONTROL "&Cancel", IDCANCEL, "Button", BS_PUSHBUTTON | WS_TABSTOP 
| WS_CHILD, 142, 84, 32, 14 


[PERERA EERE EEE REAR EERE E EERE EERE RHEE HERRERA EERE EERE EEE EEE RHEE EEE EH 
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* 
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* 
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COLORCTL.H , « 
Header file for COLORCTL.DLL * 


* 


PEER ER EERE RE TERE E EERE EERE EEE ERE RE REE E EEE EERE EE HERRERA E HERR ERR EERE REE ES / 


/* ColorCtl styles */ 
#define CCS_RECT 0x0001L 
#define CCS_ROUND 0x0002L 


/* dialog control IDs */ 


#define IDID 100 

#define IDCC 101 

#define IDRED 102 

#define IDREDIT (1000+IDRED) 
#idefine IDGREEN 103 

#define IDGEDIT (1000+IDGREEN) 
#define IDBLUE 104 

#define IDBEDIT (1000+IDBLUE) 
#define IDSAMPLE 105 

#define IDBORDER 106 

#define IDRECT 107 

#define IDROUND 108 


/* color values */ 


#define MAXCVAL OxFF 
#define GRAYVAL 0x80 
#define DEFRGB RGB (GRAYVAL, GRAYVAL, GRAYVAL) 


(continued) 
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Figure 4-5. continued 


/* miscellany */ 
#define COLORCTLCLASSNAME "ColorCtl" 
#define ARRN(a) (sizeof a / sizeof a[0]) 


/*** FUNCTION PROTOTYPES ***/ 


/* defined in COLORCTL.C */ 
LONG PASCAL FAR ColorCtlWndFn( HWND, WORD, WORD, LONG ); 
DWORD PASCAL FAR HexToDWord( LPSTR ); 


PRSHHE HEHEHE HEEFT EEEE HHH HEEHESEREHEAEEH HEHEHE SHEET HEERES HEHE EHHREEEHEE EE EEE RES 


- * 
f 


; COLORCTL.DEF module-definition file * 


* 
‘ 


PPS HRHHHEHSH RTH HEE ERE HEHEHE EES HEHE REESE SELAH EE SEESEREEH ERE EHEEEP ERE HTEEEE HE EH OEE 


LIBRARY COLORCTL 

DESCRIPTION ‘COLORCTL version 1.0' 

STUB ‘WINSTUB.EXE' 

EXETYPE WINDOWS 

CODE LOADONCALL MOVEABLE DISCARDABLE 

DATA PRELOAD MOVEABLE SINGLE 

HEAPSIZE 1024 

SEGMENTS INIT_TEXT PRELOAD DISCARDABLE 
WEP_TEXT PRELOAD FIXED 

EXPORTS WEP @1 RESIDENTNAME 


ColorCtlinfo @2 
ColorctlStyle  @3 
ColorctlFlags @4 
ColorCtlWndFn @5 
ColorCtlDlgFn (6 


"=< Colarctl Samples’ 


Figure 4-6. 
Six ColorCtl controls with different shapes and colors. 
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The basic structural components of COLORCTL.DLL—LibMain Which initial- 
izes the library and registers the class), the class window function ColorCtl- 
WndFn, and WEP—represent only about a third of the DLL’s source code. This 
source code is found in INIT.C, COLORCTL.C, and WEP.C. The rest of the source 
code, in DLGEDIT.C, provides the resource-editor interface. 


Initialization and Class Registration 


The library’s initialization function, LibMain, registers the custom-control class 
with the CS_GLOBALCLASS style. The control class also has the CS_DBLCLKS 
style so that you will be able to double-click the control within a resource editor 
to view the control’s style dialog box. The initialization function also stores the li- 
brary’s module handle in a global variable. The module handle is later used in 
DLGEDIT.C to identify a dialog resource compiled as part of the library. 


The Class Window Function 

The window function for the ColorCi#l class is named ColorCtlWndFn and is de- 
fined in COLORCTL.C. The window function contains no additional code in sup- 
port of the resource-editor interface—there is no difference between a ColorCtl 
control created by a resource editor and one created by any other application. 


The DLL Exit Function 

As it is in all DLLs, the exit function is named WEP and is exported with the 
RESIDENTNAME attribute. Unlike the RYG.DLL example earlier in this chapter, 
COLORCTL.DLL has no cleanup actions to carry out when Windows unloads the 
library. Therefore WEP is a do-nothing function. 


Three of the other four exported functions in COLORCTL.DLL provide the 
resource-editor interface. These functions are ColorCtlInfo, ColorCtiStyle, and 
ColorCtlFlags. The fourth, ColorCtilDigFn, supports the dialog box displayed 
when the resource editor calls ColorCctiStyle. 


The Info Function 


A resource editor calls the Info function to determine the characteristics of the 
custom-control class. For example, when you choose the Add Custom Control 
command from the SDK Dialog Editor’s File menu and then specify ColorCti in 
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the Add Control dialog box, the Dialog Editor calls ColorCtlInfo to determine the 
default class name, size, and style of the control. 


The Info function returns a handle to a global-memory block that contains 
descriptive information for the custom-control class. This information is format- 
ted as a CTLINFO data structure. (This data structure is declared in 
CUSTCNTL.H, a C-language include file provided in the Windows SDK.) The 
SDK Dialog Editor refers to the CTLINFO data whenever the editor creates a new 
custom-control window. 


The Style Function 


A resource editor calls the Style function to let you specify the style of a particu- 
lar custom control. In the SDK Dialog Editor, this happens when you choose the 
Style command from the Edit menu or when you double-click on a control that 
has the CS_DBLCLKS style. The Style command displays a dialog box that lets 
you edit a particular control’s CreateWindow parameters. A resource editor calls 
the Style function with a CTLSTYLE data structure containing a set of default 
style parameters. The Style function modifies these parameters according to your 
input in the dialog box. 


In the ColorCtl example, the style function ColorCtlStyle displays a modal dialog 
box that lets you specify the control’s color and border styles. The return value 
from the call to DialogBoxParam indicates whether you have modified the 
values in the CTLSTYLE data structure. 


Although most of a control’s style attributes can be modified at your discretion, 
the control’s ID requires special handling to ensure that its value is unique 
among the controls that are used within a dialog box. Typically, a resource editor 
assigns a unique default ID value to each new control. The resource editor then 
lets the Style function validate the ID value by passing the addresses of two 
callback functions as parameters. The Style function can call the first of the 
callback functions (/pfnIdToStr) to discover the ID value that the resource editor 
has assigned. If you change the control’s ID value, the Style function can call the 
other callback function (/pfnStrTold ) to inform the resource editor of the new ID 
value and to allow the editor to verify that the changed ID value is unique. 


The Flags Function 


The Flags function builds a string of symbols that represent the style of a custom 
control. A resource editor uses the string returned by the Flags function to build 
a CONTROL statement in a resource-script file. 
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The ColorCtlFlags function uses the wFlags parameter to build a text string con- 
taining the appropriate style names separated by vertical bars (the logical OR op- 
erator used in a CONTROL statement). The function returns the final length of 
the text string. Although ColorCtlFlags builds the string without monitoring its 
length, a Flags function that builds a long text string should verify that the string 
length does not exceed the maximum buffer size specified in the wMaxLen 
parameter. . 


The Style Dialog Function 


The style dialog function supports a dialog box displayed by the Style function. 
The dialog’s purpose is to let you update the values in the CTLSTYLE data struc- 
ture for a particular custom-control window. In general, this dialog box should 
contain both OK and Cancel buttons. If you choose OK, the Style function should 
return updated CTLSTYLE data to the resource editor. If you choose Cancel, the 
CTLSTYLE values should remain unmodified. 


The ColorCtiDigFn function supports the dialog box illustrated in Figure 4-7. If 
you choose the OK button, the function first updates the CTLSTYLE values by 
calling GetStyleInfo and then calls EndDialog with a nonzero return value. It 
calls EndDialog with a return value of 0 if you choose Cancel or if you use the 
Esc key to end the dialog. 


ColorCtl Control Style «.. 


Figure 4-7. 
The dialog box that is displayed when the Dialog Editor calls the 
ColorCtlStyleFn function. 


Building the Perfect Control 


When you intend to use a custom control as a general-purpose tool, you need to 
give careful thought to the control’s visual design and to the details of its func- 
tionality. Like the predefined Windows controls, custom controls should blend 
into the Windows environment so that they cooperate well with their parent 
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windows as well as with other controls. As you fine-tune a custom-control class, 
you may want to adopt some of the techniques that Windows’ predefined control 
classes use for memory management, client-area painting, and communicating 
with a parent window. 


Managing the Input Focus 


A control should provide a visual indication that it has the input focus. For ex- 
ample, edit controls highlight their contents; list-box controls outline the cur- 
rently selected item with a dotted-line rectangle; scroll-bar controls display a 
blinking caret in the scroll-bar thumb; and button controls display a modified 
border and a dotted-line rectangle around the button text. If your custom control 
can use the same focus indication as one of the default control classes, users will 
intuitively recognize when your custom control has the input focus. 


Memory Allocation 


There are several different ways for a custom control to allocate memory. Be- 
cause controls are windows, you can store limited amounts of data in window 
extra bytes and window property lists. If a control needs more than a few bytes 
of data, however, it should call LocalAlloc or GlobalAlloc to obtain a block of 
memory. It can then store the block’s memory handle in window extra bytes. 


If you use LocalAlloc, be sure you know which local heap you are using. Nor- 
mally, calling LocalAlloc from a library function allocates memory in the li- 
brary’s local heap. If you use a DLL’s local heap, be certain to specify a nonzero 
value in a HEAPSIZE statement in the DLL’s module-definition file. 


If a custom control must process long lists of data elements, you might also want 
to allow the control’s owner to allocate memory and to pass memory handles to 
the control. This is a technique that is used by edit controls, which use the class- 
specific EM_SETHANDLE and EM_GETHANDLE messages to manage memory 
handles. 


Notifying the Parent Window 


You should also consider using one or more messages to let a custom control no- 
tify its parent when the control’s status changes. The method used by the pre- 
defined Windows controls is to send WM_COMMAND to the parent, with the 
control ID in wParam, the control’s window handle in the low-order word of 
lParam, and a notification code in the high-order word of /Param. 
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A custom control that accepts keyboard input might send a WM_COMMAND 
message to its parent whenever it processes a keystroke. The EN-CHANGE 
notification code sent by an edit control is an example of this. A custom control 
could also support an owner-draw style by sending WM_DRAWITEM messages 
to its parent, as do button, list-box, and combo-box controls that have owner- 
draw styles. 


A control can provide an additional degree of flexibility by sending WM_CTL- 
COLOR messages to its parent. The method for sending WM _CTLCOLOR is 
shown in the function MsgEraseBkgnd in the file COLORCTL.C. The control's 
window function sends WM_CTLCOLOR to the parent in response to 
WM.ERASEBKGND, which is sent to the control’s window function by Begin- 
Paint. The device-context handle associated with WM_ERASEBKGND is the 
same as the one returned by BeginPaint, and the control’s window function uses 
this handle when it sends WM_CTLCOLOR. 


The WM_CTLCOLOR message is useful for ColorCtl controls because it lets a 
control’s parent determine how to paint the control’s background. If the parent 
lets DefWindowProc process WM_CTLCOLOR, the control’s background color 
will be the same as the default window background. However, if the parent pro- 
cesses WM_CTLCOLOR by returning a handle to a brush, the control will use 
that brush to paint its background. (This works even if the parent window is a 
dialog box.) The parent of a ColorCtl control can also prevent the control from 
erasing its background by returning the handle of a null brush in response to 
WM_CTLCOLOR. 


Painting Control Styles 


Whenever you design a custom control, pay particular attention to the way the 
control is painted, especially if the control supports more than one visual variant. 
Sometimes a control’s final design reflects a compromise between visual con- 
sistency and functionality. For example, if you design a control that displays text, 
you may want the text to be displayed at the same location in each control win- 
dow regardless of whether the control displays a border. On the other hand, it 
may be more convenient to work with a text-display control in which the posi- 
tion of the text can vary to minimize the amount of space necessary to display 
the text. Figure 4-8 illustrates the latter design in two edit controls, only one of 
which has the WS_BORDER style. 
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ABCDE 


Figure 4-8. 

The edit control on the left has the WS_BORDER style; the one on the right does 
not. Both controls are the same size, but the window text is aligned differently 
in each. 


In the case of the Colorctl custom control, the visual design derives from the 
control’s purpose, which is to fill itself with a color. The control displays a rect- 
angle, an ellipse, or a round-cornered rectangle whose size is bounded by the 
control’s window rectangle, not by the client area. This design prevents gaps be- 
tween adjoining ColorCtl controls and allows you to align or overlap multiple 
ColorCtl controls without needing to adjust the controls’ size or border style. 


The control’s visual design depends on selective processing of the WM_NC- 
PAINT and WM_PAINT messages. For a window with the WS_BORDER style, 
Windows’ default action is to draw a rectangular black border in response to the 
WM_NCPAINT message. Because this obviously will not work for ColorCil con- 
trols that have non-rectangular styles, the Co/orCtl window function traps 
WM_NCPAINT and paints the border itself in response to WM_PAINT messages. 
This is convenient because the window function calls Rectangle, Ellipse, or 
RoundRect to paint the control’s client area, and these GDI functions can draw a 
border as well as fill the client area with color. 


For this approach to work, however, the control window’s client area must al- 
ways correspond to the entire control-window rectangle. This is a problem if the 
window has the WS_BORDER style because Windows’ default action is to shrink 
the window’s client area to leave room for the border. For this reason, the win- 
dow function traps WM_NCCALCSIZE, which prevents DefWindowProc from 
reducing the client-area size for controls with the WS_BORDER style. 


Although this technique seems straightforward, it creates an additional com- 
plication for ColorCtl controls that do not have the WS_BORDER style. The 
problem is that the Rectangle, Ellipse, and RoundRect functions always draw a 
border, even if you select a null pen for the current device context. The solution 
is to increase the size of the drawing rectangle with a call to InflateRect. This 
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causes the border to be clipped outside the control’s client area, so the filled in- 
terior of the rectangle, ellipse, or round-cornered rectangle extends to the edge 
of the control’s window rectangle. 


These complications could be avoided by restricting the ColorCt/ control’s style 
to rectangles with a border. However, the control class is more powerful because 
it supports variations in its border and shape styles. The price of additional func- 
tionality in a custom-control class is usually additional programming effort. 


You may find that the goal of building a perfect custom control is an elusive one. 
If you reflect on the RYG and ColorCtl examples earlier in this chapter, you will 
probably think of ways to improve their appearance or their functionality. 
For example, both control classes would benefit from the ability to respond to 
user input. In fact, there’s no end to the tinkering you might do to make these 
custom controls—or any other custom control—a bit more flexible or prettier to 
look at. Nonetheless, the extra effort is worthwhile. Well-designed custom con- 
trols make Windows applications easier to write and easier to use. 


132 


An Object- 
Oriented View 


5: AN OBJECT-ORIENTED VIEW 


If you program in an object-oriented environment such as Smalltalk-80, you’ll be 
happy to learn that the Windows environment contains some familiar object- 
oriented design ideas, but you’ll be disappointed that Windows doesn’t support 
object-oriented programming constructs more fully. Even if you’re more com- 
fortable with procedural programming and unfamiliar with object-oriented con- 
cepts, understanding Windows’ object-oriented roots can help you design better 
source code for your Windows applications. 


This chapter looks at Windows from an object-oriented point of view. Windows 
itself is not an object-oriented programming environment, but the underlying 
structure of the Windows environment is clearly influenced by object-oriented 
software concepts. This chapter describes those concepts and shows how you 
can use them in the design of your own Windows applications. 


Objects and Messages 


The term “object” has different meanings in different contexts. By now, you’re 
surely familiar with global-memory objects, local-memory objects, and GDI ob- 
jects. You have also encountered object libraries and object modules, in which 
an object is something generated by a compiler or an assembler. In this chapter, 
however, an object is none of these. Instead, an object is a particular kind of 
programming construct used in a style of programming called object-oriented 
programming. 


Object Structure 


A typical object-oriented programming environment consists of a variety of pre- 
defined objects arranged so that they can transfer control to each other in a 
hierarchical fashion. Each of these objects consists of both executable code and 
data. The executable code describes a set of predefined actions the object can 
perform. The data is private to the object—that is, it is accessed only by the 
associated executable code. In the parlance of object-oriented programming, 
this localization of predefined actions and private data within an object is called 
encapsulation. 


From this point of view, an object is not a complicated entity. You can easily 
imagine a straightforward C function that uses a switch statement to define a set 
of actions that access data stored in locations known only within the function it- 
self. (f you think this description sounds suspiciously like a Windows window, 
you’re absolutely correct.) 
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A natural characteristic of the design of an object-oriented environment is that 
objects transfer control to each other using messages. A message is represented 
as a set of data items that can be transferred between objects. Sending a message 
is equivalent to executing a function call with parameters that represent the mes- 
sage data. One of the parameters in this function call is a predefined data item 
that identifies the message. When an object receives a message—that is, when 
the executable function that performs an object’s actions is called with a mes- 
sage identifier and other parameters—the message identifier determines which 
action the object carries out. 


As a Windows programmer, you are already familiar with the technique of using 
messages to evoke actions. The power of this technique lies in the fact that dif- 
ferent objects can respond to the same message with different actions. This 
means that a particular message can represent a single generic event such as a 
keystroke, mouse movement, or video-display update, yet any particular mes- 
sage can evoke quite different actions in different objects. There are many ob- 
vious examples of this in the Windows environment: Consider the different ways 
in which windows can process the same WM_KEYDOWN, WM_MOUSEMOVE, 
or WM_PAINT message. 


It’s harder to follow a program’s flow in a message-driven environment than in a 
procedural operating environment. There are at least two reasons why this is so. 
One is that messages can be sent to an object either by another object or by the 
operating environment itself. In Windows, for example, messages such as 
WM_KEYDOWN and WM_MOUSEMOVE originate within the operating envi- 
ronment, whereas messages such as WM_SETFONT originate within 
applications. 


Another reason is that an object can process a message by sending one or more 
new messages to other objects or even to itself. If you are analyzing program 
flow, you may find that carrying out even a simple action involves processing a 
cascade of messages. This is why debugging a Windows application often in- 
volves monitoring the messages the application processes. 


Although the order in which an object receives messages is somewhat unpredict- 
able, the actions taken by the object to process each message are explicitly 
defined. Of course, objects do not explicitly define actions for every possible 
message. Instead, objects rely on an implicit default action to be carried out for 
any message not explicitly processed. The usual mechanism that objects use 
for default message processing is to pass messages to another object. 
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Message-Passing Hierarchy 


In an object-oriented programming system, objects are related to each other in a 
hierarchical structure that reflects the flow of messages between the objects. 
When an object receives a message, one of its possible actions may be to 
retransmit the message to another object that lies above it in the hierarchy. A 
message-passing hierarchy implies that an object can always respond to a mes- 
sage with a default action—namely, the action performed by the next object in 
the hierarchy. 


The topmost objects in an object hierarchy are naturally the most generic in 
their actions because they provide the default actions for any messages passed to 
them from objects below them in the hierarchy. In a very simplistic object 
hierarchy, the topmost object is simply a “black hole” that ignores all messages it 
receives. In a real-world programming environment, however, the topmost ob- 
ject may carry out a variety of generic default actions. 


A message-passing hierarchy is a powerful programming paradigm because an 
object lower in the hierarchy can make use of the functionality of objects above 
it in the hierarchy simply by passing messages up the hierarchy. Such use of the 
hierarchy is characteristic of object-oriented programming systems. It is also im- 
plicit in the message-passing mechanisms supported in Windows. 


Windows as Objects 


In the Windows environment, you can regard windows as objects. Each window 
is associated with private data and with a window function that explicitly defines 
a set of actions to be carried out in response to one or more specific messages. If 
a window function does not explicitly process a message, it passes the message 
to another window function in a loosely hierarchical fashion. 


You can think of DefWindowProc as the topmost function in a message-passing 
hierarchy. DefWindowProc carries out a variety of generic actions common to 
most windows in the Windows environment, such as drawing a window’s non- 
client area, responding to system commands to resize and move a window, and 
updating a window’s text caption. Def WindowProc also serves as a “black hole” 
for many messages. About one third of the documented WM_* messages are pro- 
cessed by DefWindowProc in Windows 3.0. Def WindowProc does nothing with 
the others except return a value of 0. 


The messages ignored by DefWindowProc are intended for processing by other 
window functions. Because Def WindowProc carries out the basic actions com- 
mon to most windows, most window functions perform specialized actions in 
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response to certain messages and pass the remaining messages up the hierarchy 
to DefWindowProc for default processing. 


Message-Passing in Windows 


In a true object-oriented programming environment such as Smalltalk-80, the 
mechanisms by which objects pass messages to other objects are explicitly de- 
fined. In Windows, however, message-passing is implemented as a function call 
that can occur anywhere within a window function. The way a message passes 
from one window function to another depends on how the calling window func- 
tion executes the function call and on which function is called. 


In principle, the path of a message through the Windows hierarchy is simple: A 
message is passed—from window function to window function—until it is 
trapped and processed by a window function that recognizes it. The problem is 
that some messages must always be passed up the object hierarchy, whether or 
not they are processed in a window function, because DefWindowProc and 
other default functions (such as those associated with the predefined control 
classes) carry out essential actions in response to some messages. 


Unfortunately, you don’t always know which messages can be safely trapped in a 
window function and which must be passed through. To be on the safe side, a 
window function should trap only those messages whose default processing it 
needs to override. All other messages should be passed up the hierarchy either 
before or after they are processed in the window function. 


This means a window function can handle a message in one of four ways. The 
window function can trap the message without passing it up the object 
hierarchy; it can process the message and then pass it on; it can pass the message 
up the hierarchy and then process it; or it can simply pass the message on. 


Figure 5-1 illustrates all four kinds of message processing. The function 
NumEditWndFn supports an edit-class window that recognizes only numeric in- 
put. The function passes most messages up the object hierarchy to the default 
edit window function by calling the CallWindowProc function, but it traps 
WM_CHAR messages by setting the bCWP variable to FALSE for any character 
that does not represent numeric input. The NumEditWndFn function also pro- 
cesses the WM_SETFOCUS message after the message has been transmitted to 
the default edit window function. In this way, NumEditWndFn displays a special 
caret instead of the caret created by the default edit window function in re- 
sponse to WM_SETFOCUS. 
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FARPROC pDefEditWndFn; /* pointer to the default 
edit window function */ 


LONG PASCAL FAR 
NumEditWndFn( HWND hWnd, WORD wMsg, WORD wParam, LONG 1Param ) 
{ 

LONG 1RVal = OL; 

BOOL bCWP = FALSE; 


switch( wMsg ) 


{ 
case WM_CHAR: 


bCWP = iscntrl(wParam) |! isdigit(wParam) i: 
(NULL != strchr( "+-.", wParam )); 
break; 
default: 

bCWP = TRUE; 
break; 

} 

if( DCWP ) 


1RVal = CallWindowProc( pDefEditWndFn, 
) hWnd, wMsg, wParam, 1Param ); 


if( WM_SETFOCUS == wMsg ) 
{ 


/* create a fat caret */ 
CreateCaret( hWnd, 0, 4, 16 ); 
ShowCaret ( hWnd ); 

} 


return 1RVal; 
} 


Figure 5-1. 
Source code for NumEditWndFn, a window function for an edit control that 
allows only numeric input. 


Missing from this view of window-objects arranged in a message-passing 
hierarchy is an efficient way to create a new object with specified functionality 
in its proper place in the hierarchy. In Windows, this is accomplished by using 
another object-oriented programming construct: the class. 
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Class Structure 


In an object-oriented environment, a class describes the characteristics of a set 
of similar objects. In Windows, a class specifies such characteristics as the class 
name and the address of the window function to be used by all objects Cwin- 
dows) in the class. When you call CreateWindow, you specify the class whose 
characteristics apply to the window being created. This is much more efficient 
than explicitly specifying all the characteristics of every window you create, as 
you might if classes did not exist. 


By using classes, Windows can create multiple objects—that is, multiple win- 
dows—using only one copy of the executable code that defines a class’s func- 
tions. Different windows within the same class are distinguished only by private 
data (parent-window handle, child-window ID, window-function address, win- 
dow extra bytes, and so on) that are associated with each window. Windows 
assigns a unique handle to each newly created window and uses the handle to 
identify the window’s private data. Applications access a window’s private data 
through the API functions SetWindowWord, GetWindowWord, SetWindowLong, 
and GetWindowLong. 


Window classes are also associated with private data. (However, window classes 
do not process messages, so don’t think of them as objects.) You initialize a 
class’s private data in the WNDCLASS data structure that you use with 
RegisterClass. Windows subsequently refers to this data when you call 
CreateWindow to create a window in the class. You can use several API func- 
tions—including GetClassInfo, GetClassLong, GetClassWord, SetClassLong, and 
SetClass Word—to access a class’s private data. 


In Windows, window functions implement the hierarchical flow of messages. Be- 
cause window classes contain the addresses of window functions, you can use 
classes to describe the message-passing hierarchy within a Windows application. 
However, there is no class hierarchy in Windows that completely describes the 
hierarchical flow of messages. Window functions such as DefWindowProc do 
not correspond to any class. 


Windows also lacks an intrinsic mechanism for subclassing—that is, for creating 
a new class that inherits functionality from a class hierarchy. Each time you 
register a new class, you must explicitly define the private data and window 
function of the class. You cannot implicitly describe the default functionality of a 
new class by relying on inheritance from a previously defined class. 
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Nevertheless, subclassing is a useful programming technique in Windows. To 
create a subclass, you use GetClassInfo to copy a class’s private data into a 
WNDCLASS data structure. You then modify the private data and provide the 
address of a new window function that passes unprocessed messages to the 
original class’s window function. When you call RegisterClass with a new class 
name and the modified WNDCLASS data structure, you create a new subclass 
with a unique set of characteristics. The subclass can inherit some or all of the 
functionality of the original class, depending on how the window function of the 
subclass passes messages to the window function of the original class. You can 
then use the subclass to create new windows. 


Figure 5-2 illustrates how you might create the NumEdit class, a subclass of the 
default edit control class. The subclass, whose window function is shown in 
Figure 5-1, recognizes only numeric input. The NumEdit subclass inherits all the 
functionality of the default edit class because the NumEdit class window func- 
tion (NumEditWndFn) passes all unprocessed messages to DefEditWndFn, the 
edit-class window function. 


char szNumEditClass[] = "NumEdit"; 
FARPROC pDefEditWndFn; 


BOOL RegisterNumEditClass( HANDLE hInstance ) 


{ 
WNDCLASS' wc; 


/* get default WNDCLASS values for the edit class */ 
GetClassInfo( 0, "Edit", &wc ); 


/* save the address of the default edit window function */ 
pDefEditWndFn = (FARPROC)wc.lpfnWndProc; 


/* register the NumEdit subclass */ 


wc. hInstance = hInstance; 
we.lpszClassName = szNumEditClass; 
we.lpfnWndProc = NumEditWndFn; 


return RegisterClass( &wce ); 


} 


Figure 5-2. 
Creating a subclass of the edit control class. The subclass is named NumEdit; 
the subclass window function is named NumEditWndFn. 
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From this object-oriented perspective, what is sometimes called subclassing in 
Windows isn’t really subclassing. The Windows SDK documentation uses the 
term “subclassing” to describe a different technique that creates “subclasses” on 
a window-by-window basis. This technique, shown in Figure 5-3, associates a 
new window function with a particular window by using GetWindowLong to 
steal the address of the window’s original window function from the window’s 
private data and then calling SetWindowLong to redirect the window’s messages 
to a new window function that filters some of the messages. In effect, filtering 
messages in this way changes a window’s location in Windows’ message-passing 
hierarchy, but it does not actually involve the creation of a new class or subclass. 


FARPROC pDefEditWndFn; 


void InstallFilterFunction( HWND hEdit ) 


{ 
FARPROC pThunk; 


pThunk = MakeProcInstance( (FARPROC)NumEditWndFn, hInstance ); 
pDefEditWndFn = 
(FARPROC) SetWindowLong( hEdit, GWL_WNDPROC, (LONG)pThunk ); 


void UninstallFilterFunction( HWND hEdit ) 
{ 
FARPROC pThunk; 


pThunk = (FARPROC) SetWindowLong( hEdit, GWL_WNDPROC, 
(LONG) pDefEditWndFn ); 
FreeProcInstance( pThunk ); 


} 


Figure 5-3. 

Installing and uninstalling a window function that filters messages without 
creating a new window subclass. In this example, the function NumEditWndFn 
is installed to filter the messages sent to the edit-class window hEdit. 


Classes and the Appearance of Objects 


Apart from their convenience as a programming construct, classes intuitively 
describe the elements of Windows’ graphical interface. By predefining a set of 
useful classes, Windows makes it easy to create windows that have a great deal 


142 


5: AN OBJECT-ORIENTED VIEW 


of built-in functionality as well as a consistent visual style. It is no coincidence 
that the predefined control-class names describe the different entities that ap- 
pear on the screen. 


In Windows, characteristics such as an object’s visual appearance and default 
functionality are part of a class description. This creates an intuitive connection 
between window classes and the visual appearance of windows on the screen. 
As a programmer, you can think of ListBox as the name that identifies a particu- 
lar class; as a Windows user, you can easily visualize the corresponding set of list 
box controls. 


° rm 
Objects and Data 
Part of the design of objects in an object-oriented programming environment is 
the association of private data with each object. You can regard window extra 
bytes and property lists as two different mechanisms for associating private data 
with windows as objects. 


Window Extra Bytes 


When you call CreateWindow, Windows allocates a fixed-size data structure that 
is private to the new window. This data structure contains the window’s instance 
handle, parent-window handle, window-function address, and other data that 
Windows uses to manage the window. The same data structure can be made 
larger than the minimum size used by Windows’ window manager to store sev- 
eral extra bytes of private data. The extra bytes of data in the data structure are 
ignored by the window manager and can be used freely by your programs. 


Because window extra bytes contain data that is private to a particular window, 
it makes sense to use them to keep track of data on a window-by-window basis. 
The only method for manipulating this private data is through the API functions 
GetWindowWord, GetWindowLong, SetWindowWord, and SetWindowLong, 
which access window extra bytes by using a window handle. 


The number of extra bytes allocated for a window is specified by the window’s 
class. This means that, to use window extra bytes, you must first register a win- 
dow class that specifies the number of window extra bytes to be allocated for 

_ windows in the class. When you call RegisterClass, the cbWndExtra value in the 
WNDCLASS data structure specifies the number of extra bytes of data to associ- 
ate with windows in the class. When you subsequently create a window in the 
class, CreateWindow allocates the specified number of extra bytes and associ- 
ates it with the window’s handle. 
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The nature and format of the data you store in window extra bytes are entirely 
up to you. However, the API functions are clearly designed to store and retrieve 
only small chunks of data. If you want to associate more than 6 or 8 bytes of data 
with a window, you should allocate a block of memory by using GlobalAlloc or 
LocalAlloc, store the data in the memory block, and store the memory handle in 
the window extra bytes: 


/* allocate a 1-KB block of private data */ 
hMem = GlobalAlloc( GHND, 1024L ); 


/* store the handle in the window extra bytes */ 
SetWindowWord( hWnd, 0, hMem ); 


When you do this, you must manage the handle stored in the window extra 
bytes. For example, if you call GlobalReAlloc to change the size of the memory 
block, you must also update the value stored in the window extra bytes. Also, 
you should free the memory block when the window is destroyed: 


case WM_DESTROY: 
GlobalFree( (GLOBALHANDLE) GetWindowWord( hWnd, 0 ) ); 
break; 


The problem with using window extra bytes is that you must design your appli- 
cation so that the layout of every window’s extra bytes is known. This can be in- 
convenient if you use window extra bytes differently in different window 
classes. To be smart about the layout of window extra bytes in windows of dif- 
ferent classes, your program must determine a window’s class—perhaps by a 
call to GetClassName—before it accesses the window’s extra bytes. 


Using window extra bytes is also problematic if you use subclasses. If you use 
GetClassInfo to create a subclass of a class that uses window extra bytes, the 
subclass must allocate additional extra bytes so that the original class’s extra 
bytes are not clobbered. Later, when you create a window in the subclass and ac- 
cess its extra bytes, you must skip over the extra bytes used in the original class, 
as shown in Figure 5-4. 


Property Lists 


An elegant way to avoid the problems with window extra bytes is to use prop- 
erty lists. Instead of identifying a window’s private data items with an offset into 
a data structure, the property-list API lets you assign names to a window’s pri- 
vate data items. 
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int nEBStart; /* a global variable */ 
void RegisterTheSubclass( ... ) 
{ 

WNDCLASS wc; 


/* save the current number of window extra bytes */ 
GetClassInfo( ..., &we ); 
nEBStart = wc.cbWndExtra; 


/* allocate additional extra bytes for the subclass */ 
we.cbWndExtra += sizeof (WORD) ; 


RegisterClass( &wc ); 


} 


void AccessTheExtraBytes( ... ) 
{ 


/* access the extra bytes (skip the previous allocation) */ 
SetWindowWord( hWnd, nEBStart, wData ); 


wData = GetWindowWord( hWnd, nEBStart ); 
} 


Figure 5-4. 
Allocating and using window extra bytes in a subclass. In this example, 2 extra 
bytes (one word) are allocated for the subclass. 


Although the terminology is borrowed from the Lisp language, property lists in 
Windows are not really the same as property lists in Lisp. In Lisp, a language 
based on list-processing concepts, properties represent only one of a variety of 
ways to manipulate lists. In Windows, a property is nothing more than a data 
item associated with a particular window and identified by name; a property list 
is a list of a window’s properties. You can regard a window’s properties as pri- 
vate data items identified by names. 


Windows provides a set of straightforward API functions for manipulating prop- 
erties. To associate a private data item with a window, you use the SetProp 
function: 


SetProp( hWnd, lpName, hData ); 
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The window handle )Wnd identifies the window; the string /pName contains 
the name of the data item; and /Data is a handle to a local or global block of 
memory that contains the data. (Actually, you can use bData to represent not 
only memory handles but any 2-byte data item.) Windows does the internal list 
processing required to keep track of the names and data handles associated with 
each window. 


To access the data, you call GetProp using the window handle and name you 
passed to SetProp: 


hData = GetProp( hWnd, lpName ); 


To discard the property, you call RemoveProp: 


hData = RemoveProp( hWnd, lpName ); 


Before you destroy a window, you must call RemoveProp for each property you 
have associated with the window. 


In general, you should use property lists when you want to name the private data 
items associated with a window. Property lists are also easier to use than win- 
dow extra bytes in cases where you want to associate private data with 
pre-existing windows without usable window extra bytes. 


When you use property lists, you must carefully manage both the property data 
items and the property names. The amount of data directly associated with a 
property name is only 2 bytes, the size of a Windows handle. This means you 
must always access a property data item indirectly unless the data item is itself 
only 1 or 2 bytes long. 


One feature of Windows’ property-list API is that the same property name can 
be associated with different windows, regardless of the window class or the ap- 
plication to which a particular window belongs. The catch is that you must be 
careful to use unique property names when you add to a window’s property list. 
If you call SetProp with a pre-existing property name, the function will simply 
update the data associated with the property name. If you want to ensure that a 
property name is unique when you use it, call GetProp with the new property 
name before you call SetProp to add the property to a window’s property list; if 
GetProp returns 0, the property name was not previously associated with the 
window. 
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Atoms as Property Names 


In some programs, you might find it convenient to use atoms instead of strings as 
property names. An atom is an unsigned integer value that uniquely identifies a 
string stored by Windows in a hash table. Windows’ atom manager supports both 
global and local atoms. The hash table for local atoms is stored in a module’s local 
heap; the hash table for global atoms is stored in the global heap. 


You can use either a local or a global atom as a property name. To do this, call 
AddAtom or GlobalAddAtom to create an atom, and then use the atom instead 
of a string pointer when you call the property-list API functions. When you call 
SetProp, GetProp, and RemoveProp, the atom must be passed in the low-order 
word of the /pName parameter, with the high-order word set to 0. You can use 
the MAKEINTATOM macro to do this conversion: 


aAtom = GlobalAddAtom( lpName ); 
SetProp( hWnd, MAKEINTATOM(aAtom), hData ); 


Two Programming Examples 


The following section presents two source-code examples that look at Windows 
from an object-oriented point of view in that they treat windows as objects with 
private data. These examples use the property-list API to implement functions 
that might otherwise be considerably more awkward to develop. 


Using a Property List 

The first example, in Figure 5-5 on the next page, consists of two functions, 
ShowWaitCursor and HideWaitCursor. These two functions use the property-list 
API to associate a cursor handle with a specified window handle. This technique 
lets a program call the functions with any window handle as the parameter 
without the need to save and restore the cursor handle in a static variable 
elsewhere in the program. 


ShowWaitCursor uses LoadCursor and SetCursor to change the current cursor 
shape to an hourglass. ShowWaitCursor calls SetProp to add the specified win- 
dow’s previous cursor handle to the window’s property list. The string szPropID 
identifies the cursor handle in the property list. The complementary function 
HideWaitCursor calls RemoveProp to extract the cursor handle from the prop- 
erty list and to remove the szPropID property. HideWaitCursor then restores the 
cursor through a call to SetCursor. 
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/* property name */ 
char szPropID[] = "hPrevCursor"; 


[RPE e eR EERE RHEE EEE H ERASER ERASE TEES OH ERE E ERSTE HOHE THREES SHORE EERE EE HED 
* * 
* ShowWaitCursor * 
* j * 


HORE RHEE EEO E EERE EE ER EEE EH EE EER EEE EE EHEEE HEE E ESSER REST REESE ES EH EHO RHEE RE REESE / 


- static void ShowWaitCursor( HWND hWnd ) 


{ 
HCURSOR hCursor; 
hCursor = GetProp( hWnd, szPropID ); 
if( 0 == hCursor )- 
{ 
/* display the wait cursor */ 
ShowCursgor( TRUE ); 
hCursor = SetCursor( LoadCursor( 0, IDC_WAIT ) ); 
/* save the previous cursor handle in the window's property list */ 
SetProp( hWnd, szPropID, hCursor ); 
} 
} 
[PERERA EEE REE E EERE HERRERA EERE EERE ER HERES ERE R EERE EEE RHEE EERE EERE ERE HERE REED 
* HideWaitCursor a . 
* y * 


FEPPREHEE REE RE FERRERS EERE EE ERE EE HERE R ER ERR ESTHER EE HERE ER RE RR ERE REET HH E RE HRA E / 


static void HideWaitCursor( HWND hWnd ) 


{ 
HCURSOR hCursor; 


/* xemove the property from the window's property list */ 
hCursor = RemoveProp( hWnd, szPropID ); 


if( 0 != hCursor ) 

{ 
/* display the previous cursor */ 
SetCursor( hCursor ); 
ShowCursor( FALSE ); 


} 


Figure 5-5. 
Source code for ShowWaitCursor and HideWaitCursor. 
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The second example, shown in Figure 5-6, illustrates an alternative technique for 
filtering the messages processed by a window function. This technique uses the 
property-list API to store the address of a window’s default window function. 
The advantage to using a window’s property list instead of a static variable to 
store this address is that you can associate different default window functions 
with different windows without modifying the window function that does the 
message filtering. 


EAHA EEE EERE ERE E RHEE RHEE EERE ERE EEE EE EEE EEE ERR E EERE REE RE REE EEEE EEE 


# * 
# NMAKE description for KEYTRAP.EXE - 
# * 


FARR EERE EEE HEHE EERE REE HEHEHE ERE PEER EE EERE EE EERE EERE TEETER REET EE EEE REE EH 


.c.obj: 
cl /AM /c /G2sw /Osw /W4 /Zlp $*.c 


ALL: keytrap.exe 
keytrap.obj: keytrap.c keytrap.h 
keytrap.res: keytrap.rec keytrap.h keytrap.ico 


re /r keytrap.rc 
keytrap.exe: keytrap.obj keytrap.res keytrap.def 


link /al:16 /nod /noe keytrap, , , libw mlibcew, keytrap.def 
re keytrap.res 


[RRR E EERE EERE EERE REE EERE EERE EERE RHEE EERE EERE HERE E EERE EEE R ER EEE REE EE HE 


* * 
* KEYTRAP .C + 
* * 
* Exports: TopLevelWndFn ape e 
* KeyTrapWndFn * 
* * 


FREER EERE EERE ERE H ETRE EEE REE EEE E REET EERE EERE RHEE RETR EEE ERR ERR EERE REE HH / 


#define NOCOMM 
#include <windows .h> 
#include “"keytrap.h" 


Figure 5-6. (continued) 
Source code for KEYTRAP.EXE. 


149 


Windows: Developer’s Workshop 


Figure 5-6. continued 


/*** FUNCTION PROTOTYPES ***/ 


typedef struct 
{ 
FARPROC pThunk; 
FARPROC pDefWndFn; 
} FNSTRUC; 


typedef FNSTRUC NEAR * NPFNSTRUC; 


LONG PASCAL FAR TopLevelWndFn( HWND, WORD, WORD, LONG ); 
LONG PASCAL FAR KeyTrapWndFn( HWND, WORD, WORD, LONG ); 


static HWND Init ( HANDLE, HANDLE, int ); 
static void InstallKeyTrap( HWND ); 
static void UninstallKeyTrap( HWND ); 


/*** GLOBAL VARIABLES +*+**/ 

char szTopLevelClass[] = KEYTRAPCLASSNAME; 
char szAppTitle[] = "Key Trap"; 

char szFNStruc[] = "FNStruc"; 


HANDLE hiInstance; 


[REAR R ESE E REE EEE HARE EOE H HERE EERE RHEE EERE EEE R ERE ERE R HEHEHE EEE EEE RED 


* * 
* WinMain 7 
* * 


SHRP E EERE R EE EERE SHEAR THERE EHH EE EEE HEHE EERE EHH OEE H EEE HE EET HER ERE HER EH EHH / 


int PASCAL 
WinMain( HANDLE hInst, HANDLE hPrevinst, LPSTR lpszCmdLine, int nCmdShow ) 
{ 
ier eae waa? 
MSG msg; 


hWnd = Init( hInst, hPrevInst, nCmdShow ); 
if( 'hWnd ) 
return 0; 


while ( GetMessage( &msg, 0, 0, 0) ) 
{ 


TranslateMessage( &msg ); 
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DispatchMessage( &msg ); 


} 


return msg.wParam; 


[PEPER NERA TREE EERE EET E EEE E DEFER ERE EHEHESEE SEES EHH E ESP EETE RHE ET EER EEE HE EEE SH 


* 


* Init 


* 


* 


* 


* 


PREP ETE EERE RHEE EEE EERE EEE E TEER TERE R ETOH TREES EEE HEHE THERE EERE HERR RE EEE / 


static HWND Init( HANDLE hInst, HANDLE hPrevInst, int nCmdShow ) 


{ 


WNDCLASS we; 
HWND hWnd; 


if( !hPrevInst ) 
{ 


/* register the top-level window class */ 


we. lpszClassName 
we .hInstance 

wo. lpfnWndProc 
we. hCursor 

we .hIcon 

we. lpszMenuName 
we .hbrBackground 
we.style 
we.cbClsExtra 
we.cbWndExtra 


if( !RegisterClass ( 


return 0; 


} 


szTopLevelClass; 

hinst; 

TopLevelWndFn; 

LoadCursor( 0, IDC_ARROW ); 
LoadIcon( hinst, "TopLevelicon" ); 
NULL; 

COLOR_WINDOW#1 ; 

CS_HREDRAW ! CS_VREDRAW; 

0; 

DLGWINDOWEXTRA; 


&éwe ) ) 


/* return 0 if unsuccessful */ 


/* save the instance handle +/ 


hInstance = hinst; 


/* create and display a top-level window 
and several child controls +/ 
hWnd = CreateDialog( hInst, szTopLevelClass, 0, NULL ); 


ShowWindow( hWnd, nCmdShow ); 


return hWnd; 
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Figure 5-6. continued 


[REE E EERE REE EEE EDR EH EEE EE REE ERASE EEE EEE REE ERO R REST EERE SEER EE EERE EER ED 


* hi : * 
* TopLevelWndFn inten * 
# goer * 


RENEE AER E EEE A ARERR E EEE HERE EERE RETA EE HERA REPT E EERE EERE EE RHEE HEH EERE HE HEE S / 


LONG PASCAL FAR 
TopLevelWndFn( HWND hWnd, WORD wMsg, WORD wParam, LONG lParam ) 
{ 

LONG 1RVal = OL; 

BOOL DDWP = FALSE; 

int n; 


switch ( wMsg ) 
{ 
case WM_SETFOCUS: 
SetFocus ( GetDlgItem( hWnd, IDKEYTRAP ) ); 
break; 


case WM_COMMAND: 
if ( IDKEYTRAP == wParam ) 
{ 
if( IsDlgButtonChecked( hWnd, IDKEYTRAP ) ) 
for( n=IDCTLFIRST; n<=IDCTLLAST; nt+ ) 
InstallKeyTrap( GetDlgItem( hWnd, n ) ); 


else 
for( n=IDCTLFIRST; n<=IDCTLLAST; n++ ) 
UninstallKeyTrap( GetDlgItem( hWnd, n) ); 


break; 


case. WM_DESTROY: 
PostQuitMessage( 0 ); 
break; 


default; 
bDWP =. TRUE; 
break; 
} 


if ( bDWP. ) be ; 
1RVal = DefWindowProc( hWnd, wMsg, wParam, lParam ); 


return 1RVal; 


(continued) 
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Figure 5-6. continued 


DARE heheh kkk teketeheth tk heheh tkehehted keheiteh eh teledeheh h teheh kek ktelekeh ch kelahetstetehehetehehctelelelehctebeteielel 


* KeyTrapWndFn * 


RENTER EERE HERE RHEE EERE EEE EERE EEE E EERE ER ER EER EERE R EER HER ERE ERE RRR EES / 


LONG PASCAL FAR 
KeyTrapWndFn( HWND hWnd, WORD wMsg, WORD wParam, LONG lParam ) 
{ 

LOCALHANDLE hFNStruc; 

NPFNSTRUC pFNStruc; 

FARPROC pWndFn; 


/* process the F1 key */ 
if( (WM_KEYDOWN == wMsg) && (VK_F1 == wParam) ) 
MessageBox( hWnd, “You pressed the F1 key", szAppTitle, MB_OK ); 


/* get a pointer to the default window function */ 
hFNStruc = GetProp( hWnd, szFNStruc ); 

pFNStruc (NPFNSTRUC) LocalLock( hFNStruc ); 
pWndFn = pFNStruc->pDefWndFn; 

LocalUnlock( hFNStruc ); 


/* call the default window function */ 
return CallWindowProc( pWndFn, hWnd, wMsg, wParam, lParam ); 


[REE REE HER EERE REE EERE EEE EEE EE EEE ERE REET ERE REE ERE R EERE E HERE EEE EEE E EEE EE EH 


* InstallKeyTrap * 
* * 


HHH REER HERRERO REE E EE EEE H HEE E RHEE E EEE EEE HERRERA ERT E ER ERE EERE RRR EEE / 


static void InstallkeyTrap( HWND hWnd ) 
{ 

LOCALHANDLE hFNStruc; 

NPFNSTRUC pFNStruc; 


/* allocate storage for pointers to the window functions */ 
hFNStruc = LocalAlloc( LHND, sizeof (FNSTRUC) ); 
pFNStruc.=. (NPENSTRUC) LocalLock( hFNStruc ); 


/* save the window-function pointers */ 
pFNStruc->pThunk = MakeProcInstance( (FARPROC)KeyTrapWndFn, hInstance ); 


pFNStruc->pDefWndFn = 
(FARPROC) SetWindowLong( hWnd, GWL_WNDPROC, (LONG) pFNStruc->pThunk °); 


(continued) 
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Figure 5-6. continued 


LocalUnliock( hFNStruc_) ; 


/* save the handle to the pointer data structure ‘/ 
SetProp( hWnd, szFNStruc, hFNStruc ); 


[ARERR EERE EEE EEE EERE EERE EEE E EEE EE EERE EERE EE REE REE E REE E HER EERE EHH EERE EE OD 


* * 
* UninstallkeyTrap * 
* * 


PEEE ER EEE EERE EEE HERE ERE REE E SH EEE SEER EEE EE RSE SEER EE HERE RHEE REE HEHE EEE R PERE S EES / 


static void UninstallKeyTrap( HWND hWnd ) 
{ 

LOCALHANDLE hFNStruc; 

NPFNSTRUC pFNStruc; 


/* point to the pointer data structure */ 
hFNStruc = RemoveProp( hiind, szFNStruc ); 
pFNStruc = (NPFNSTRUC) LocalLock( hFNStruc ); 


/* restore the default window-function pointer */ 
SetWindowLong( hWnd, GWL_WNDPROC, (LONG) pFNStruc->pDefWndFn ); 
FreeProciInstance( pFNStruc->pThunk ); 


/* discard the data structure */ 


LocalUnlock( hFNStruc ); 
LocalFree( hFNStruc ); 


é [REAR EET EERE EERE EEE EE EE SEER EEE EERE ESHER H ETRE EERE EER EERE OTTER EE = 


* : * 
* KEYTRAP.RC resource script . 
* : . * 


HEPRR RHEE EERE SEER ERE ERE E EAE ARERR AREA TEER RHEE EERE EERE ERT ERE H ERE RHE TRE / 


#include <windows.h> 
#include “keytrap.h" 


/* icons */ 


TopLevelicon ICON keytrap.ico 


(continued) 
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Figure 5-6. continued 


KeyTrap DIALOG PRELOAD MOVEABLE DISCARDABLE 42, 32, 236, 54 
CAPTION "Key Trap" 
CLASS KEYTRAPCLASSNAME 
STYLE DS_ABSALIGN | WS_OVERLAPPED | WS_ CAPTION {| WS_SYSMENU | WS_MINIMIZEBOX 
{ 
CONTROL "Key Trap", IDKEYTRAP, "Button", BS_AUTOCHECKBOX | WS_TABSTOP | 
WS_CHILD, 4, 20, 42, 12 
CONTROL "", 0, "Static", SS_BLACKRECT | WS_CHILD, 48, 0, 1, 54 
CONTROL "ListBox", 0, "Static", SS_CENTER | WS_CHILD, 52, 2, 66, 8 
CONTROL "", IDLISTBOX, "ListBox", LBS_SORT | WS_BORDER i WS_VSCROLL i 
WS_TABSTOP i WS_CHILD, 52, 12, 66, 33 
CONTROL "Edit", 0, "Static", SS_CENTER ! WS_CHILD, 122, 2, 66, 8 
CONTROL "", IDEDIT, "Edit", ES_MULTILINE : WS_BORDER i WS_TABSTOP | 
WS_CHILD, 122, 12, 66, 33 
CONTROL "Button", IDBUTTON, "Button", BS_PUSHBUTTON { WS_TABSTOP i 
WS_CHILD, 192, 12, 38, 33 


[RARER EAE EE REED EERE RHEE EEO HE EERE EERE TEES EERE EEE E REET REET THERE DRE ER EEE EH 


* * 
* KEYTRAP .H . 
* * 


REET EERER ESTER TEER EEE REPRE SEER EEE HESS SEES HERE SHER ESHER EEE EERE ESE EEE HEHE ES / 


#define KEYTRAPCLASSNAME "KeyTrap" 
#define IDCTLFIRST 100 

#define IDKEYTRAP {IDCTLFIRST) 
#define IDLISTBOX (IDCTLFIRST+1 ) 
#define IDEDIT (IDCTLFIRST+2) 
#define IDBUTTON (IDCTLFIRST+3) 
#define IDCTLLAST (IDCTLFIRST+3) 


FEHR HAA ARES EEEEHESERAHELEEEHERGEEHHRAEE HELA HEREEHEHEEAEREHE RHR REDE SHOES HE REE DD 
. * 
, 

; KEYTRAP.DEF module-definition file * 


. * 
’ 


PRHARHHEHEEAREHHEEEREEEREEEAERELERE HEH EEEEHHEEREEHEE LEH EEEEKREELEE SERRE RRHE EEE DH 


DESCRIPTION 'KEYTRAP.EXE: version 1.0! 
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Figure 5-6. continued 


EXETYPE WINDOWS 
STUB 'WINSTUB.EXE' 
CODE LOADONCALL MOVEABLE DISCARDABLE 
DATA PRELOAD MOVEABLE MULTIPLE 
SEGMENTS _TEXT . PRELOAD MOVEABLE DISCARDABLE 
HEAPSIZE 512 
STACKSIZE 5120 
EXPORTS TopLevelWndFn 
KeyTrapWndFn 


The KEYTRAP application uses message filtering to trap the WM_KEYDOWN 
message associated with a particular keystroke. When you call InstallKeyTrap 
with the parent window’s handle, KeyTrapWndFn becomes a message-filter 
function for all four child-window input controls in the application. InstallKey- 
Trap saves the previous window-function address in the local heap and adds the 
local-memory handle to the window’s property list. 


KeyTrapWndFn passes messages up the hierarchy by using GetProp to locate the 
address of the appropriate window function and then calling CallWindowProc. 
The only message that KeyTrapWndFn filters is the WM_KEYDOWN message 
that represents the F1 key. In response to this message, KeyTrapWndFn displays 
a message box. Filtering continues until UninstallKeyTrap executes. Uninstall- 
KeyTrap restores the previous window-function address and cleans up the win- 
dow’s property list. 


These examples show how having an object-oriented point of view can add use- 
ful generality to your Windows source code. The next step is to embody the 
object-oriented aspects of the Windows environment in an object-oriented pro- 
gramming language in which objects and classes are easier to manipulate than 
in a procedural language such as C or Pascal. You might want to explore one of 
the object-oriented programming languages available for Windows program- 
ming, such as Smalltalk, Actor, or C++. Even in C, however, you can improve the 
design of your Windows applications by taking advantage of object-oriented 
design elements in Windows. 


6: DYNAMIC DATA EXCHANGE (DDE) 


Windows is a multitasking environment in which several programs can execute 
concurrently. It is only natural for concurrent Windows programs to share data 
with each other. Windows users realize this intuitively by using the clipboard to 
transfer data among applications. 


Although the clipboard is an excellent tool for user-initiated data transfers, its 
design is not well suited to direct interprocess communication in which Win- 
dows applications share data without user intervention. This is where Dynamic 
Data Exchange (DDE) plays its role. DDE allows Windows applications to com- 
municate directly to share both data and computational tasks. 


In the original DDE specification, introduced in version 2 of Windows, DDE is 
implemented through a set of Windows messages and data structures defined in 
a C-language include file, DDE.H, in the Windows SDK. The printed protocol for 
using DDE messages is also part of the Windows SDK. In 1991, Microsoft released 
the DDE Management Library (DDEML). The DDEML supports a set of API func- 
tions that manage DDE communications at a higher level of abstraction than the 
message-based DDE protocol. 


The DDEML was actually implemented using the message-based DDE protocol, 
so existing Windows applications that use DDE messages are compatibile with 
DDEML-based applications. However, you should use the DDEML rather than 
message-based DDE in new Windows applications. The DDEML API is superior 
because it hides the details of DDE message processing and because it offers ad- 
ditional functionality beyond the capabilities of the message-based DDE pro- 
tocol. The following discussions of DDE’s transaction-based communication 
model and of the message-based DDE protocol should help you appreciate the. 
overall design of DDE-based interprocess communication. However, you should 
move on to the subsequent discussion of the DDEML when you design your DDE 
applications. 


Conversations and Transactions 


DDE applications share data by means of conversations. A DDE conversation is a 
logical connection between two different applications, in which the two applica- 
tions alternately transmit data to each other. A Windows application can support 
multiple DDE conversations, so any Windows application can exchange data 
with several other applications at the same time. 


Each DDE conversation is structured as a series of transactions between a client 
and a server. Each transaction consists of a request for data or services and a 
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corresponding response. The difference between a DDE client and a DDE server 
lies in the kinds of transactions that each can initiate. A DDE client can initiate 
any of the following transactions: 


Enumerate DDE services and topics. 
Establish a conversation with a server. 
Request a data item from a server. 
Establish a data link with a server. 
Terminate a data link. 

Send a data item to a server. 


Request a server to execute one or more commands. 


Terminate a conversation. 

Only two transactions can be initiated by a DDE server: 
m@ Send a data item to a client. 

@ Terminate a conversation. 


Because a DDE conversation is always initiated by a client, a DDE server must be 
executing before a client attempts to initiate the conversation. 


Message-Based DDE 


In message-based DDE, both the client and the server in a DDE conversation are 
windows. An application that supports DDE creates a window for each DDE 
conversation in which it participates. Each DDE window can function either as a 
client or as a server, so a single Windows application can support multiple DDE 
server and client conversations. An application creates a DDE window each time 
it begins a new conversation and destroys the window when the conversation 
terminates. During its lifetime, the DDE window’s primary responsibility is to 
process DDE messages, either as a DDE client or as a DDE server. 


Two windows carry out a DDE conversation by exchanging a series of pre- 
defined Windows messages, which are shown in Figure 6-1. The messages WM- 
—DDE_INITIATE, WM_DDE_ACK, and WM_DDE_TERMINATE permit hand- 
shaking between client and server windows in a DDE conversation so that the 
windows can exchange messages in an orderly, synchronized manner. The 
WM_DDE_REQUEST, WM_DDE_ADVISE, and WM_DDE_UNADVISE messages 
control when data is transferred between windows, and the WM_DDE_DATA 
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and WM_DDE_POKE messages accompany the data itself. Finally, the WM- 
_DDE_EXECUTE message allows an application to execute commands or per- 
form some other service on behalf of another application. 


Message Description Parameters 


Initiating and terminating a conversation 


WM_DDE_INITIATE Initiate a DDE HIWORD(/Param): aTopic 
conversation LOWORD(/Param): aService 
WMDDE_TERMINATE Terminate a DDE 
conversation 


Acknowledging receipt of a DDE message 


WM_DDE_ACK Acknowledge a See Figure 6-2 on page 163. 
DDE message 


WM_DDE_-REQUEST Request a one- HIWORD(/Param): altem 
time data LOWORD (lParam): cfFormat 
transfer 
WM_DDE-_ADVISE Request a data link HIWORD(/Param): altem 
LOWORD (/Param): bDDEADVISE 
WM_DDE_UNADVISE Terminate a HIWORD(/Param): altem 
data link LOWORD (/Param): cfFormat 
Data transfer 
WM_DDE_DATA Transfer data from HIWORD(/Param): altem 
server to client LOWORD (lParam): hDDEDATA 
WM_DDE_POKE Transfer data from HIWORD(/Param): altem 


client to server LOWORD (lParam): hbDDEPOKE 
Executing commands 


WM_DDE_EXECUTE Request server HIWORD(/Param): hCommandsString 
to execute a 
command 

Figure 6-1. 


Windows DDE messages. Parameters are packed into the high-order and low- 
order words of \Param. Parameter names starting with the letter a represent 
atoms; parameter names starting with the letter h represent global memory 
handles. DDEADVISE, DDEPOKE, and DDEDATA are data structures defined 
in the include file DDE.H. (See also Figure 6-3 on page 166.) 
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The message-based DDE specification requires most DDE messages to be trans- 
mitted by using PostMessage. SendMessage is used only for WM_DDE_INITIATE 
and for WM_DDE_ACK messages sent in response to WM_DDE_INITIATE. The 
wParam parameter of PostMessage and SendMessage always contains the win- 
dow handle of the message sender. The high-order and low-order words of the 
lParam parameter contain values whose meanings are different for each DDE 
message. 


To put the DDE messages into perspective, consider how they are used in the 
context of a DDE conversation. The following overview groups the DDE mes- 
sages according to the way they are used in transactions: initiating and terminat- 
ing a conversation, acknowledging receipt of a message, data control, data 
transfer, and executing commands. 


Initiating and Terminating a Conversation 
The WM_DDE_INITIATE message is sent by a DDE client to all potential DDE 
servers. The client broadcasts the message to all overlapped and pop-up win- 


dows in the Windows system by calling SendMessage with a destination window 
handle of FFFFH: 


SendMessage( OxFFFF, WM_DDE_INITIATE, hClientWnd, lParam ); 


Potential servers reply to the client by calling the SendMessage function with the 
WM_DDE_ACK message. The /Param parameter in the WM_DDE_ACK 
message contains two global atoms that identify the server and a topic of 
conversation. 


The WM_DDE_TERMINATE message can be sent by either partner in a DDE 
conversation to terminate the conversation. The /Param parameter is not used in 
this message. 


Acknowledging Receipt of a DDE Message 


The WM_DDE_ACK message is used to acknowledge a variety of DDE messages 
at different times in a DDE conversation. The content of the /Param parameter 
for WM_DDE_ACK depends on which message is being acknowledged, as 
shown in Figure 6-2. 
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Message Parameters Notes 

Acknowledged 

WM_DDE_INITIATE HIWORD(/Param): aTopic Sent by server to client. 
LOWORD(Param): aService Informs client of 


server’s support for 
specified topic. 
WM_—DDE_DATA HIWORD(/Param): altem Sent by client to server. 
LOWORD(/Param): wStatus Acknowledges receipt 
of data. Used only 
when explicitly 
requested by server. 


(See fAckReg bit in 
DDEDATA, Figure 
6-3.) 
WM_DDE_POKE HIWORD(/Param): altem Sent by server to client. 
LOWORD(/Param): wStatus Acknowledges receipt 
of data. 
WM_DDE_EXECUTE HIWORD(/Param): hCommands _ Sent by server to client. 
LOWORD(/Param): wStatus Acknowledges execu- 
tion of a command 
string. 
WM_—DDE_REQUEST HIWORD(Param): altem Sent by server to client. 
LOWORD(/Param): wStatus Used only for negative 


acknowledgment of 
request for data. 


WM_DDE_ADVISE HIWORD(/Param): altem Sent by server to client. 
LOWORD(/Param): wStatus Acknowledges initiation 
of a data link. 
WM_DDE_UNADVISE HIWORD(Param): altem Sent by server to client. 
LOWORD(/Param): wStatus Acknowledges termi- 


nation of a data link. 


Figure 6-2. 
Use of the WM_DDE_ACK message to acknowledge DDE messages. 


Data Control 


The WM_DDE_REQUEST message can be posted by a client to request that a 
server transmit a particular data item. The /Param parameter describes the data 
item by name and specifies a data format. The server responds to a WM_DDE- 
—REQUEST message by posting a WM_DDE_DATA message containing the re- 
quested data. 
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The WM_DDE_ADVISE message sets up a data link between server and client. 
By using a DDE data link, a server can send data items to a client without re- 
quiring the client to request each data item explicitly. The /Param parameter of 
WM_DDE_ADVISE describes the name and format of a data item; it also de- 
scribes the handshaking method to be used for individual data transfers within 
the data link. 


A client initiates a data link by posting WM _DDE_ADVISE to a server. The 
server acknowledges the data link by posting a WM_DDE_ACK message to the 
client. The server can then post unsolicited data to the client. The data link con- 
tinues until the client terminates it by posting WM_DDE_UNADVISE or until the 
conversation is terminated with WM_DDE_TERMINATE. 


Data Transfer 


The WM_DDE_DATA and WM_DDE_POKE messages are used to transfer data 
between DDE windows. The WM_DDE_DATA message is used to transfer data 
from a server to a client, either in response to an explicit WM_DDE_REQUEST 
message from the client or as part of an ongoing data link. WM_DDE_POKE is 
used to transfer data from a client to a server. The /Param parameter in both 
messages identifies the data with a global atom and also contains a handle to a 
global memory object that contains the data being transferred. 


A client uses the WM_DDE_EXECUTE message to transmit commands to a 
server. To use WM_DDE_EXECUTE, a client formats a character string that con- 
tains one or more commands and passes a reference to the character string in 
the WM_DDE_EXECUTE /Param parameter. The server parses the command 
string, executes the commands, and posts WM_DDE_ACK to the client to 
acknowledge that the commands were processed. 


Service, Topic, and ltem Names 


The DDE specification uses a three-level hierarchy to describe the data content 
of a DDE conversation. This descriptive hierarchy consists of a service name, a 
topic of conversation, and the name of a particular item of data. When a DDE 
conversation is initiated, the server and client must agree on both the name of 
the service and the topic of conversation. After the conversation is established, 
specific data values can be referenced by name and transferred between the cli- 
ent and the server. 
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The following conversation is a not-quite-realistic analogy of how this descrip- 
tive hierarchy works. In this example, a client initiates a conversation with a 
server by specifying Customer Support (service) on the Windows SDK (topic) 
and by requesting a price (item of data): 


Client (sends WM_DDE_INITIATE): Hello, is this Customer Support 
(service name)? I’d like to initiate a conversation about the Windows 
SDK (topic name). 


Server (sends WM_DDE_ ACK): Yes, this is Customer Support (service 
name). I will be happy to converse with you about the Windows SDK 
(topic name). 


Client (posts WM_DDE_REQUEST ): What is the price (item name) of 
the Windows SDK? 


Server (posts WM_DDE_ DATA): The price (item name) is $19.95. 
Client (posts WM_DDE_TERMINATE): OK, goodbye. 
Server (posts WM_DDE_TERMINATE): Goodbye. 


A DDE server uses the three-level naming hierarchy to describe the context in 
which it provides data to DDE clients. A server application can support one or 
more service names, each of which supports multiple topics. The server makes 
different sets of data items available to clients in the context of each service- 
topic combination it supports. 


A DDE client exploits this three-level descriptive scheme to discriminate among 
potential data servers in order to obtain a particular item of data. A client can 
select a particular service by name, or it can enumerate multiple services that 
support a particular topic and then choose among them to initiate a conversa- 
tion. In either case, it can then request specific data items by name and format. 


The hierarchical naming strategy is powerful because a client can identify data 
using only descriptive names. The DDE naming hierarchy hides the details of a 
server’s implementation from a client. The client needs no special knowledge 
about a server’s implementation, whether the server is reading disk files, trans- 
ferring data across a network or a remote communications link, or calculating 
data on the fly. 


Traditionally, a Windows application that acts as a DDE server uses its applica- 
tion name (module name) as a DDE service name. For example, the Windows 
Program Manager application, PROGMAN.EXE, supports the DDE service name 
ProgMan. However, a single Windows application can support multiple DDE ser- 
vice names, each of which may differ from the application name, and each of 
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which may cover a different gamut of topics. Moreover, an application can 
change the services and topics it supports in response to changing circum- 
stances. For example, a DDE application that performs remote communications 
might support a particular service name only when a link to a remote computer 
is active. 


Working with DDE Data 


In DDE, data values are exchanged by storing them in shared global memory. 
DDE messages use two kinds of global data: shareable global-memory blocks 
and global atoms. Shareable global-memory blocks provide the means of trans-. 
ferring data between applications. Global atoms represent service, topic, and ~ 
data-item names. All DDE messages except WM_DDE_TERMINATE use atom 
handles and global-memory handles as parameters by packing them into the 
low-order and high-order words of /Param. 


Shareable Global Memory 


Every global-memory block associated with a DDE message is formatted with 
one of three predefined data structures: DDEADVISE, DDEPOKE, or DDEDATA. 
These three data structures are shown in Figure 6-3. Each of the data structures 
starts with a 16-bit word of flag bits followed by a 16-bit integer, cfFormat, which 
contains a clipboard-format value that describes the format of the shared data. In 
DDEDATA and DDEPOKE, the data structures used with WM_DDE_DATA and 
WM_DDE_POKE, these two 16-bit values are followed by actual data. 


/* DDEADVISE: used with WM_DDE_ADVISE */ 
typedef struct 
{ 


unsigned reserved: 14, /* bits 0-13 */ 
£DeferUpd: 1, /* bit 14 */ 
fAckReq: 1; /* bit 15 */ 
int cfFormat; 
} 
DDEADVISE; 


‘/* DDEPOKE: used with WM_DDE_POKE */ 
typedef struct 


{ 
unsigned unused: 13, /* bits 0-12 */ 


Figure 6-3. (continued) 
Data structures used with DDE messages. These data structures are defined in 
DDE.H in the Windows SDK. 
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Figure 6-3. continued 


fRelease: 1, /* bit 13 */ 
fReserved: 2; /* bits 14-15 */ 
int cfFormat; 
BYTE Value [1]; 
} 
DDEPOKE ; 


/* DDEDATA: used with WM_DDE_DATA */ 
typedef struct 
{ 


unsigned unused: 12, /* bits 0-11 */ 
fResponse: 1; /* bit 12 */ 
_f£Release: 1, /* bit 13 */ 
reserved: 1, /* bit 14 */ 
fAckReq: 1; /* bit 15 */ 

int cfFormat; 

BYTE Value [1]; 

} 
DDEDATA; 


The DDE specification requires that the global memory allocated for DDEDATA 
and DDEPOKE data structures be shareable. Shareable global-memory blocks 
are allocated using the GMEM_DDESHARE flag in the call to GlobalAlloc: 


hMem = GlobalAlloc( GHND ! GMEM_DDESHARE, 
dwDataSize + sizeof(DDEDATA) ); 


GDI Objects 


In addition to shareable global-memory blocks, you can also share GDI objects 
in a DDE conversation. Do this by using handles to GDI objects as data in 
DDEDATA or DDEPOKE data structures. For example, a DDE server can share a 
GDI bitmap by passing the handle returned by CreateBitmap or CreateCom- 
patibleBitmap as data in the Value array of the DDEDATA data structure in a 
WM_DDE_DATA message. 


Global Atoms 


In message-based DDE, global atoms generally reference plain-text strings that 
represent service, topic, and item names. You might find it convenient, however, 
to use integer strings instead of text strings, particularly if your application refer- 
ences a large number of different data items. (An integer string is an integer for- 
matted as an ASCII string preceded by the # character. For example, #32666 is 
the integer-string representation of the integer 32666.) Also, don’t forget that 
atoms are case-insensitive: System and SYSTEM represent the same atom. 
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In general, the sender of a DDE message creates the atoms associated with the 
message with a call to GlobalAddAtom. The recipient uses GlobalFindAtom or 
GlobalGetAtomName to identify the atoms associated with the message. The re- 
cipient can then delete the atom by calling GlobalDeleteAtom, or it can reuse the 
same atom if it needs to post a message in reply. 


There are two exceptions to this rule. If PostMessage fails to post a DDE mes- 
sage, the atoms associated with the message should be deleted. Also, in the case 
of the atoms used in a WM_DDE_INITIATE message, the DDE client that broad- 
casts WM_DDE_INITIATE must be the one to delete the atoms it creates. A DDE 
server that receives WM_DDE_INITIATE must not delete or reuse the atoms 
associated with the message. This makes sense because more than one server 
may respond to a single WM_DDE_INITIATE broadcast. If a server deleted the 
atoms, another server that receives the broadcast message would find that the 
associated atoms were invalid. 


Flags 

The message-based DDE protocol uses a number of flags to control the flow of 
DDE messages, to indicate the disposition of globally shared objects, and to indi- 
cate the status of various transactions. These flags appear in the predefined DDE 
data structures DDEADVISE, DDEPOKE, and DDEDATA. There are also flags in 
the status word associated with the WM_DDE_ACK message. 


Flags for message control 

The flag word in the DDE data structures DDEDATA and DDEADVISE lets you 
fine-tune two DDE message transactions. In the case of WM_DDE_DATA, the 
J[AckReq bit in the DDEDATA data structure indicates whether a client should 
acknowledge a WM_DDE_DATA message by posting WM _DDE_ACK to the 
server. If the fAckReq bit is 1, the client should post WM_DDE_ACK to the server; 
if the fAckReq bit is 0, no acknowledgment is necessary. By setting fAckReq to 1, 
a server can ensure that a client successfully processes WM _DDE_DATA mes- 
sages in the order they are received. 


In the case of WM_DDE_ADVISE, both the fAckReq and the /DeferUpd bits in 
the DDEADVISE data structure affect subsequent WM _DDE_DATA messages 
sent by the server through a data link. The fAckReq bit specifies whether the 
J[AckReq bit in subsequent WM_DDE_DATA messages should be set and thus 
whether the client will be expected to acknowledge unsolicited WM_DDE- 
_DATA messages it receives through the data link. A DDE server that supports a 
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data link copies the fAckReq value from the DDEADVISE data structure into 
each WM_DDE_DATA message it posts through the data link to the client. 


The /DeferUpd bit in the DDEADVISE data structure specifies whether the 
server will include data in the WM_DDE_DATA messages it sends through a 
DDE data link. If f/DeferUpd is 0, the server includes the global memory handle 
of a DDEDATA data structure in each WM_DDE_DATA message. If fDeferUpd is 
1, the server passes a null value instead of a global memory handle with each 
WM_DDE_DATA message. The null WM _DDE_DATA message serves as an 
alarm that notifies the client that the server has changed a data item’s value. It is 
then up to the client either to request the data by posting WM_DDE_REQUEST 
or to ignore the WM_DDE_DATA message. 


Flags for global memory 

The /fRelease bit in each DDEDATA and DDEPOKE data structure determines 
how to manage the block of global memory that contains the data structure. 
When the /Release bit is set to 1, the recipient of the WM_DDE_DATA or WM- 
_DDE_POKE message should free the memory block after it has finished using 
the block. When the /Release bit is 0, the sender of the message remains respon- 
sible for freeing the memory block; in this case, the recipient should not modify 
the data within the memory block because the sender might reuse the same 
block of memory in a subsequent data transmission. If you use this technique, be 
sure to set the fAckReq bit to 1 so that the recipient of the WM_DDE_DATA or 
WM_DDE_POKE message will post a WM_DDE_ACK message that indicates 
when it is safe for the sender to reuse the memory object. 


There is a subtle trap in this otherwise commonsense memory-management 
strategy. The problem potentially can occur whenever an application sets the 
release bit to 1 when it posts a WM_DDE_DATA or WM_DDE_POKE message. 
If the sending application terminates before the recipient of the message can ac- 
cess the memory handle, Windows’ memory manager invalidates the handle and 
frees the memory. The recipient will then be in error when it attempts to access 
the already-freed handle. 


The solution to this problem is simple. When the /Release bit is set to 1, the re- 
cipient should assume ownership of the memory block by calling GlobalReAlloc: 


hMem = GlobalReAlloc( hMem, OL, GMEM_MODIFY | GMEM DDESHARE ) ; 


Then the memory block will remain allocated even if the sending application 
terminates. 
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Status flags 

The message-based DDE specification includes flags that can be used to report 
the status of DDE transactions. The fResponse flag in the DDEDATA data struc- 
ture indicates whether a WM_DDE_DATA message was posted in response to an 
explicit WM_DDE_REQUEST (/Response=1) or as part of an active data link 
( fResponse=0). 


The WM_DDE_ACK message also uses status flags, but these are returned in a 
single word, formatted as a DDEACK data structure, in the low-order word of the 
/Param parameter of the message, as shown in Figure 6-4. The status word con- 
tains two 1-bit flags, fAck and /Busy, as well as an 8-bit, application-specific 
return value. Both the flags and the status value should be carefully managed in 
any DDE program. 


Bit Name Description 

15 JAck 1=Positive acknowledgment 

=Negative acknowledgment 
14 JSBusy 1=Busy 
0=Not busy 
8-13 (reserved) 
0-7 bAppReturnCode Application-specific return value 

Figure 6-4. 


The wStatus word in WM_DDE_ACK. This word is defined as a DDEACK data 
structure in DDE.H in the Windows SDK. 


The fAck flag indicates whether the associated WM_DDE_ACK message repre- 
sents a positive or a negative acknowledgment of a previous DDE message. For 
example, when a server posts a WM_DDE_ACK message in response to a 
WM_DDE_POKE message from a client, the server sets the fAck bit to 1 to indi- 
cate that it successfully accepted the data associated with the message; it sets 
[Ack to 0 to indicate that the data was not processed. | 


If the sender of a WM_DDE_ACK message sets the fAck bit to 0, it has the option 
of setting the fBusy bit as well. The fBusy bit indicates that the sender was tem- 
porarily unable to process a previous DDE message. In effect, setting the fBusy 
bit implies “Try again later.” Of course, if fAck is set to 1, fBusy must be 0. 


Proper use of the fBusy bit is important because the DDE specification requires 
that a DDE window process all DDE messages it receives in the order in which 
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they are received. This becomes an issue when an application performs some 
prolonged computational or communications activity in response to a DDE mes- 
sage. If the application is too busy to process subsequent DDE messages, it 
should respond to subsequent DDE messages by posting WM_DDE_ACK with 
{Busy set to 1. 


Because the message-based DDE protocol provides a consistent mechanism for 
specifying the format of shared data, cooperating DDE applications can agree on 
the data format for each data transfer. For example, when a DDE client requests a 
data item ina WM_DDE_REQUEST message, it can specify a preferred data for- 
mat in the cfFormat parameter in the low-order word of /Param. If the server 
cannot support the requested data format, it will refuse the request by returning 
WM_DDE_ACK with the /Ack bit (in the return status word) set to 0. The client 
can subsequently request alternative data formats until it finds one that the 
server can support. 


The value you specify in ¢fFormat must be a valid clipboard data format. If your 
data does not conform to one of the predefined clipboard data formats listed in 
Figre 6-5, both server and client should call RegisterClipboardFormat to regis- 
ter a clipboard format ID that can be used in subsequent DDE messages. 


Format Description 

CF_TEXT Null-terminated ASCII string 

CF_BITMAP Handle to a bitmap (defined by BITMAP data structure in 
WINDOWS.H) 

CF_METAFILEPICT Metafile picture (defined by METAFILEPICT data struc- 
ture in WINDOWS.H) 

CF_SYLK Microsoft Symbolic Link format 

CF_DIF Software Arts’ Data Interchange Format 

CF_TIFF Tagged Image File Format 

CF_OEMTEXT Same as CF_TEXT but using OEM character set 

CF_DIB Device-independent bitmap (defined by BITMAPINFO 


data structure in WINDOWS.H) 


Figure 6-5. 
Clipboard data formats defined in WINDOWS.H. 
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The DDE Management Library 


The traditional way to use DDE in a Windows application is to embed a set of 
DDE message-handling functions in the application. This is the approach 
adopted in many well-known Windows applications, including the original 
Microsoft Excel and Word for Windows. When you consider the amount of detail 
in the message-based DDE protocol, however, it becomes clear that the source 
code required to support DDE processing is better encapsulated in a dynamic 
link library. 


This is exactly the purpose of the DDEML, the DDE Management Library. The 
heart of the DDEML is a dynamic link library C(DDEML.DLL) that relieves applica- 
tions of the burden of processing individual DDE messages. Unlike message- 
based DDE, in which applications communicate directly with one another, 
DDEML-aware applications communicate with only the DDEML, as shown in 
- Figure 6-6. An application calls a set of DDEML API functions to carry out DDE 
transactions. 


Message-based DDE: 


SendMessage or FostMessage Sener 


DDEML: 


[oe 


DDEML Callback DDEML 
AFI functions function API functions 


Callback 
function 


Figure 6-6. 

In message-based DDE (top), a DDE client and server communicate directly, 
using SendMessage and PostMessage. With the DDEML (bottom), all DDE 
transactions are performed through calls from applications to DDEML API 
functions and through calls from the DDEML to a callback function in each 
application. 
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A program that uses the DDEML must include an exported callback function that 
the DDEML can call to notify the program when DDE transactions occur. Like a 
window function, a DDEML callback function is an exported far function with a 
predefined set of parameters, including a transaction-type identifer that can be 
used to select transaction-specific actions, as shown in Figure 6-7. 


HDDEDATA EXPENTRY 


DdeCallback( WORD wType, /* transaction ID */ 
, WORD wFmt, /* clipboard data format */ 

HCONV hConv, /* conversation handle */ 
HSZ hszi1, /* string handle 1 */ 

HSZ hsz2, /* string handle 2 */ 
HDDEDATA hDDEData, /* global data handle */ 
DWORD dwDatal, /* 32-bit data */ 

DWORD dwData2 ); /* 32-bit data */ 

Figure 6-7. 


A function prototype for an application-defined DDEML callback function. 


Both DDEML API functions and application-defined callback functions use data 
types and data structures that are designed to facilitate DDE transaction manage- 
ment, as shown in Figure 6-8. These data types and structures are defined in a 
C-language include file, DDEML.H, which Microsoft distributes along with the 
DDEML dynamic link library. The DDEML uses handles to identify DDE conver- 
sations (data type HCONV), lists of conversations (HCONVLIST), strings that 
represent service, topic, or item names (HSZ), and shared blocks of global 
memory (HDDEDATA). 


/* EXPENTRY is used in declaring a DDEML callback function. */ 
#define EXPENTRY export far pascal 


typedef DWORD HSZ; /* string handle */ 

typedef DWORD HDDEDATA; /* global data handle */ 

typedef DWORD HCONV; /* conversation handle */ 

typedef DWORD HCONVLIST; /* list of conversation 
handles */ 


typedef struct 
{ 


HSZ hszSvc; /* service name */ 
HSZ hszTopic; /* topic name */ 
} 
HSZPAIR; /* pair of string handles */ 
Figure 6-8. (continued) 


Some of the data types and data structures defined in DDEML.H. 
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Figure 6-8. continued 


typedef struct 
{ 


WORD cb; /* size of this data structure +/ 

WORD wFlags; /* (xeserved for future use) */ 

WORD wCountryID; /* country code for topic and 
item strings */ 

int iCodePage; /* code page for topic and 
item strings */. 

DWORD dwLangID; /* language ID for topic and 
item strings */ 

DWORD dwSecurity; /* private security code */ 

} 
CONVCONTEXT; 


typedef struct 
{ 


DWORD cb; /* size of this data structure */ 
DWORD hUser; /* user-defined data */ 
HCONV hConvPartner; /* hConv for partner */ 
HSZ hszSvePartner; /* service name of partner */ 
HSZ hszSvcNameReq; /* service requested 
for connection */ 
HSZ hszTopic; /* topic for conversation +*/ 
HSZ hszItem; /* transaction item name */ 
WORD wFmt ; /* clipboard data format */ 
WORD wType; /* current transaction ID */ 
WORD wStatus; /* ST_* conversation 
status flags */ 
WORD wConvst ; /* XST_* conversation 
status flags */ 
WORD wLastError; /* last transaction error */ 
HCONVLIST hConvList; /* link to previous hConvList */ 
CONVCONTEXT ConvCtxt; /* conversation context */ 
} 
CONVINFO; 


typedef CONVINFO FAR * PCONVINFO; 


DDENiL Transaction Processing 


A program initiates a DDE transaction by calling one of the DDEML API func- 
tions. The DDEML can then process the transaction either synchronously or 
asynchronously. When the DDEML processes a synchronous transaction, the 
transaction completes before the API function call returns. When the DDEML 
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processes a transaction asynchronously, the API function returns immediately, 
before the transaction is processed. Later, when the transaction completes, the 
DDEML notifies the program by calling its callback function. 


The ability to process transactions asynchronously is important because it lets a 
DDE application continue to run while it waits for a prolonged DDE transaction 
to complete. For example, a DDE client can post an asynchronous request for 
data to a DDE server and then carry out other actions until the server responds 
to the data request. Although both synchronous transaction-handling and asyn- 
chronous transaction-handling methods are implicit in the original DDE message 
set, implementing both kinds of transaction processing is a chore that few pro- 
grammers tackled prior to the appearance of the DDEML. 


The DDEML API 


The DDEML defines a set of 26 API functions that support both server and client 
transactions, as shown in Figure 6-9. To ensure compatibility with future ver- 
sions of Windows, the DDEML API functions frequently use DWORD (32-bit) 
data values and abstract data types such as handles to strings and global-memory 
blocks. The function prototypes for all the DDEML functions are in DDEML.H. 


Function Description 


DDEML interface management 


Parameters 


Return Value 


DdelInitialize Registers a callback func- —- Pointer to returned Result code (WORD) 
tion; sets a transaction instance identifier 
filter (LPDWORD) 

Pointer to callback func- 
tion (PFNCALLBACK) 
Command and filter flags 

(DWORD) 
Reserved: must be 0 
(DWORD) 

DdeUninitialize Terminates all DDEML Instance identifier TRUE if no error 
processing for an (DWORD) (BOOL) 
application 

DdeGetLastError Returns current DDEML Instance identifier Error code (WORD) 
error status (DWORD) 

Figure 6-9. (continued) 


The 26 DDEML API functions. 
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Figure 6-9. continued 


Function Description 


Conversation management 


DdeNameService Registers a service name 
DdeConnect Initiates a DDE 
conversation 
DdeConnectList Enumerates DDE services; 
establishes multiple con- 
versations with DDE 
servers 
DdeQueryNextServer Returns the next conversa- 
tion handle in a con- 
versation list 
DdeQueryConvinfo Obtains current status of a 
DDE conversation 
DdeDisconnect Terminates a DDE 
conversation 
DdeDisconnectList Terminates multiple 


conversations 
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Parameters Return Value 


TRUE if no error 
(BOOL) 


Instance identifier 
(DWORD) 

Service name CHSZ) 

Reserved: must be 0 CHSZ) 

Command flags (WORD) 


Instance identifier 
(DWORD) 

Service name (HSZ) 

Topic name (HSZ) 

Pointer to conversation 
context data 


Conversation handle 
(HCONV) 


(PCONVCONTEXT) 
Instance identifier Conversation-list 
(DWORD) handle CHCONVLIST) 


Service name (HSZ) 

Topic name (HSZ) 

Conversation-list handle 
(HCONV) 

Pointer to conversation 
context data 


(PCONVCONTEXT) 
Conversation-list handle Next conversation 
(HCONVLIST) handle CHCONV) 


Previous conversation 
handle CHCONV) 


Conversation handle Number of bytes of 


CHCONV) status data returned 
Transaction identifier CWORD) 
(DWORD) 


Pointer to returned status 
data for the conversation 


(PCONVINFO) 
Conversation handle TRUE if no error 
CHCONV) (BOOL) 
Conversation-list handle TRUE if no error 
(CHCONVILIST) (BOOL) 


(continued) 
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Function 


Description 


Transaction management 


DdeClientTransaction 


DdeAbandon- 
Transaction 


DdeEnableCallback 


DdePostAdvise 


Begins a client-initiated 
transaction 


Aborts an asynchronous 
transaction 


Blocks (enables) or 
unblocks (disables) 
transactions 


Updates a data link 


Parameters 


Pointer to shared global 
data or shared global- 
memory handle 
(LPBYTE) 

Data length or—1 if global- 
memory handle speci- 
fied (DWORD) 

Conversation handle 
CHCONV) 

Item name (HSZ) 

Clipboard data format 
(WORD) 

Transaction type (WORD) 

Timeout duration 
(DWORD) 

Pointer to returned result: 
synchronous-transaction 
status flags or asynchro- 
nous transaction ID 
(LPDWORD) 


Instance identifier 
(DWORD) 

Conversation handle 
CHCONV) 

Transaction identifier or 0 
to abandon all trans- 
actions (DWORD) 


Instance identifier 
(DWORD) 

Conversation handle 
(HCONV) 

Enable or disable com- 
mand (WORD) 


Instance identifier 
(DWORD) 

Topic name (HSZ) 

Item name (HSZ) 


Return Value 


Shared global-memory 
handle or status flag 
(HDDEDATA) 


TRUE if no error 
(BOOL) 


TRUE if no error 
(BOOL) 


TRUE if no error 
(BOOL) 


(continued) 
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Figure 6-9. continued 


Function Description 

Associates an application- 
defined value with a 
conversation and trans- 
action identifier 


DdeSetUserHandle 


String management 


DdeCreateStringHandle Creates a handle for a 
specified string 


DdeQueryString Obtains string data and 


length 


DdeKeepStringHandle Increments the usage 


count for a string handle 


DdeFreeStringHandle Decrements the usage 
count for a string handle 
and frees the handle if 


the count equals 0 


DdeCmpStringHandles _ Case-insensitive string 


comparison 
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Parameters 


Conversation handle 
CHCONV) 

Transaction identifier 
(DWORD) 


Application-defined value 


(DWORD) 


Instance identifier 
(CDWORD) 
String pointer (LPSTR) 


Code-page identifier (int) 


Instance identifier 
(DWORD) 
String handle (HSZ) 


Pointer to buffer to receive 
string or NULL to obtain 


string length only 
(LPSTR) 
Size of buffer C(DWORD) 


Code-page identifier Cint) 


Instance identifier 
(DWORD) 

String handle CHSZ) 

Instance identifier 
(DWORD) 

String handle (HSZ) 


String handle 1 CHSZ) 
String handle 2 CHSZ) 


Return Value 


TRUE if no error 
(BOOL) 


String handle (HSZ) 


Length of the returned 
string (DWORD) 


TRUE if no error 
(BOOL) 


TRUE if no error 
(BOOL) 


—1: string 1 < string 2; 
0: string 1 = string 2; 
1: string 1 > string 2 


(continued) 
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Function Description 


Memory management 


DdeCreateDataHandle Creates and initializes a 
block of shareable 


global memory 


Frees a block of shareable 
global memory 


DdeFreeDataHandle 


DdeAccessData Obtains a pointer to a 
block of shared, read- 


only global memory 


DdeAddData Copies data into a block of 


shared global memory 


DdeGetData Copies data from a block 


of shared global memory 


DdeUnaccessData Releases a pointer to a 
block of shared global 


memory 


‘Parameters 


Instance identifier 
(DWORD) 

Pointer to buffer contain- 
ing initial data 
(LPBYTE) 

Size of global-memory 
block (DWORD) 

Offset of start of initial 
data (DWORD) 

Item name (HSZ) 

Clipboard data format 
(WORD) 

Creation flags (WORD) 


Global-memory handle 
(HDDEDATA) 


Global-memory handle 
(HDDEDATA) 

Pointer to returned data 
length (LPDWORD) 


Global-memory handle 
(HDDEDATA) 

Pointer to data to be 
copied (LPBYTE) 

Data length (DWORD) 

Offset within the global- 
memory block 
(DWORD) 


Global-memory handle 
(HDDEDATA) 

Pointer to buffer to receive 
copied data or NULL to 
obtain data length only 
(LPBYTE) 

Data length (DWORD) 

Offset within the global- 
memory block 
(DWORD) 


Global-memory handle 
(HDDEDATA) 


Return Value 


Global-memory handle 
(HDDEDATA) 


TRUE if no error 
(BOOL) 


Pointer to global 
memory block 
(LPBYTE) 


New global-memory 
handle CHDDEDATA) 


Data length (DWORD) 


TRUE if no error 
(BOOL) 
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DDEML interface management 

Most of the DDEML API functions control an application’s DDE conversations. 
However, three important DDEML functions control an application’s interaction 
with the DDEML itself. These are Ddelnitialize, DdeUninitialize, and 
DdeGetLastError. 


An application must call Ddelnitialize before it uses any other DDEML function. 
Ddelnitialize serves two important purposes. First it passes the DDEML a 
pointer to a program’s callback function. The pointer you specify in your call to 
DédelInitialize must be that of an instance thunk (created by MakeProcInstance) 
unless the callback function is defined in a dynamic link library. 


Second DdelInitialize establishes filters for callback transactions. When you call 
DdelInitialize, you must specify one or more of the flags shown in Figure 6-10. 
The DDEML will prevent the transactions you specify from reaching the 
callback function. In general, you should use the APPCLASS_STANDARD flag 
for a server callback function. For a client callback function, use APPCLASS- 
_STANDARD | APPCMD_CLIENTONTLY so that the callback function receives 
only transactions relevant to DDE client processing. 


The APPCLASS_MONITOR flag allows a DDEML application to monitor DDEML 
activity. (The DDESPY utility provided with the DDEML is one such application.) 
However, DDEML monitoring is not as straightforward as it might appear. For ex- 
ample, a DDEML monitor application might not be aware of the DDE activity of 
message-based, non-DDEML applications. Also, a DDEML monitor application 
should not also function as a DDEML server or client. Such an application can get 
into trouble when it attempts to monitor its own DDEML activity. If you want to 
design a DDEML monitor application, you need to use additional Ddelnitialize 
flags and data structures that are defined in DDEML.H and described in the 
DDEML documentation. 


Ddelnitialize returns an application-instance identifier, a value that the DDEML 
uses to associate an instance of a Windows module (application or DLL) with its 
DDE conversations. Many of the DDEML API functions use the instance identifier 
as a parameter. You should therefore call Ddelnitialize before calling any other 
DDEML function in an application. 


The DdeUninitialize function terminates DDEML processing for an instance of 
an application. Before an application terminates, it should call DdeUninitialize 
to ensure that any active DDE conversations are terminated cleanly. In addition 
to terminating conversations with other DDEML applications, DdeUninitialize 
also posts WM_DDE_TERMINATE to message-based, non-DDEML applications 
and releases any associated data internal to the DDEML. — 


180 


6: DYNAMIC DATA EXCHANGE (DDE) 


Flag 


APPCLASS_MONITOR 
APPCLASS_STANDARD 


APPCMD_CLIENTONLY 


APPCMD-_FILTERINITS 


CBF_FAIL_SELFCONNECTIONS 


CBF_FAIL_CONNECTIONS 


CBF_FAIL_ADVISES 


CBF_FAIL_EXECUTES 
CBF_FAIL_POKES 
CBF_FAIL_REQUESTS 


CBF_FAIL_ALLSVRXACTIONS 


CBF_SKIP_CONNECT_CONFIRMS 
CBF_SKIP_REGISTRATIONS 
CBF_SKIP_UNREGISTRATIONS 
CBF_SKIP_.DISCONNECTS 
CBF_SKIP_ALLNOTIFICATIONS 


Transactions Not Sent by DDEML 
fo Callback Function 


(Used in DDEML monitoring applications) 
XTYP_MONITOR 


XTYP_CONNECT, XTYP_WILDCONNECT, 
XTYP_ADVSTART, XTYP_EXECUTE, 
XTYP_POKE, XTYP_REQUEST 


XTYP_CONNECT, XTYP_WILDCONNECT 


XTYP_CONNECT and XTYP_WILDCON- 
NECT from the same instance of an 
application 

XTYP_CONNECT and 
XTYP_WILDCONNECT 

XTYP_ADVSTART and XTYP_ADVSTOP 
(returns DDE_FNOTPROCESSED to the 
client) 

XTYP_EXECUTE (returns 
DDE.FNOTPROCESSED to the client) 


XTYP_POKE (returns 
DDE-FNOTPROCESSED to the client) 


XTYP_REQUEST (returns 
DDE_FNOTPROCESSED to the client) 


XTYP_CONNECT, XTYP_WILDCONNECT, 
XTYP_ADVSTART, XTYP_EXECUTE, 
XTYP_POKE, XTYP_REQUEST (returns 
DDE_FNOTPROCESSED to the client) 


XTYP_CONNECT_CONFIRM 
XTYP_REGISTER 
XTYP_UNREGISTER 
XTYP_DISCONNECT 


XTYP_CONNECT_CONFIRM, 
XTYP_REGISTER, XTYP_UNREGISTER, 
XTYP_DISCONNECT 


Flags used with Ddelnitialize to specify transaction filters for a DDEML 


callback function. 
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The DdeGetLastError function is a general-purpose function that a program can 
call after any other DDEML function or transaction indicates that an error has oc- 
curred. DdeGetLastError returns a value that indicates the nature of the error. 
(The DDEML.H include file defines the gamut of error values with identifiers that 
begin with DMLERR_.) The DDEML retains only one error value for calls to 
DdeGetLastError. A program should call DdeGetLastError immediately after it 
detects that an error has occurred because the next DDEML API call will update 
the error value. 


Conversation management 

There are seven DDEML API functions you can use to enumerate the services 
and topics supported by DDE server applications, to initiate and terminate con- 
versations, and to determine the current state of an active conversation. These 
functions explicitly provide the higher-level support for conversation manage- 
ment that is implicit in the DDE messages WM_DDE_INITIATE, WM_DDE- 
—ACK, and WM_DDE_TERMINATE. 


An application uses DdeNameService to register and unregister DDE service 
names. When a server application registers a service name, the DDEML keeps 
track of the name so that DDE clients can subsequently initiate conversations 
with it. When the server application no longer supports the service, the server 
calls DdeNameService again to unregister the name. The DDEML notifies other 
DDEML applications each time a name is registered or unregistered by calling 
each application’s callback function. 


A DDE client calls DdeConnect and DdeConnectList to initiate DDE conversa- 
tions. Both functions require you to specify a service name and a topic name. 
You can also use a wildcard specification (a null string handle) for the service 
name, the topic name, or both. DdeConnect establishes a single DDE conversa- 
tion (even if multiple servers support the service and topic you specify) and 
returns a handle that identifies the conversation. DdeConnectList establishes 
conversations with all servers that support the service-topic combination you 
specify and returns a handle to a list of the newly initiated conversations. 


DdeConnectList uses its fourth parameter, bConvList, to avoid duplicating exist- 
ing DDE conversations. If you call DdeConnectList more than once, you should 
specify the conversation-list handle returned from the first call to DdeConnect- 
List in subsequent calls to the function. DdeConnectList will refer to the list of 
existing conversations and establish a new conversation only if it does not dupli- 
cate a conversation already in the list. 
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A client application can use DdeQueryNextServer and DdeQueryConvInfo to 
examine the list of conversations returned by a call to DdeConnectList. The con- 
versation list is a linked list of CONVINFO data structures. DdeQueryNextServer 
uses the links to traverse the list and returns a handle to the next conversation. 
DdeQueryConvinfo returns a pointer to a specified conversation’s CONVINFO 
data. Usually, you use DdeQueryNextServer and DdeQueryConvinfo in a loop 
such as the following: 


HCONVLIST hConvlList; 
HCONV hConv; 
CONVINFO Convinfo; 


/* create or update a conversation list */ 
hConvList = DdeConnectList( ... ); 


/* get a handle to the first conversation in the list + / 
/* by specifying a null handle to the previous conversation */ 
hConv = DdeQueryNextServer( hConvList, OL ); 


while( hConv ) 
{ 


/* get conversation info for the current hConv */ 
DdeQueryConvinfo( hConv, QID_SYNC, &ConviInfo ); 


/* examine the contents of the ConviInfo data structure */ 


/* get the next conversation handle in the list */ 
hConv = DdeQueryNextServer( hConvList, hConv ); 


} 


The DdeDisconnect and DdeDisconnectList functions complement DdeConnect 
and DdeConnectList. You use DdeDisconnect to terminate a single conversation 
and DdeDisconnectList to terminate all conversations in a list. Both of these 
functions are intuitive and easy to use, yet there is a common situation in which 
you don’t need them at all: If an application is about to shut down, it can im- 
plicitly terminate all its DDE conversations simply by calling DdeUninitialize. 


Transaction management 


Of the five DDEML API functions that specifically control DDE transactions, 
DdeClientTransaction is the key to DDEML transaction management. Except for 
initiating and terminating conversations, all DDE client transactions originate 
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with a call to DdeClientTransaction, including requests for data, establishing 
and terminating data links, sending data to a server, and requesting a server to 
execute a command. In effect, DdeClientTransaction subsumes all the func- 
tionality implicit in the WM_DDE_REQUEST, WM_DDE_ADVISE, WM- 
_~DDE_UNADVISE, WM_DDE_POKE, and WM_DDE_EXECUTE messages in 
the message-based DDE protocol. 


The parameter list to DdeClientTransaction includes a transaction identifier 
whose value (XTYP_REQUEST, XTYP_ADVSTART, XTYP_ADVSTOP, XTYP- 
~POKE, or XTYP_EXECUTE) specifies which transaction you want to perform. 
Most of the other DdeClientTransaction parameters have intuitive uses—to 
identify a particular conversation, to specify an item name, to point to data or to 
a command string, to specify a clipboard data format, and to point to a variable 
that contains a result-code value after the function returns. 


The one remaining function parameter, a timeout value, lets you control whether 
a transaction executes synchronously or asynchronously. If you want a transac- 
tion to execute synchronously—that is, to be complete at the time the call to 
DdeClientTransaction returns—you specify a nonzero timeout value in milli- 
seconds. The DDEML will wait for a response from the server for the specified 
duration of time. If the server fails to respond, DdeClientTransaction imposes a 
timeout and indicates that an error occurred by returning a value of 0. While the 
DDEML waits for a server response, it enters a message-processing loop that 
allows application message processing to continue. 


The minimum timeout required for successful DDE transaction processing de- 
pends on several factors, including the amount of time needed to process data or 
execute a command and the speed or configuration of the computer system on 
which Windows is running. A timeout period of 1000 ms (one second) is a rea- 

_ sonable value in most applications. In an application such as a remote communi- 
cations server, in which response to DDE timeouts can be important, you may 
want to support user-configurable timeout values. You might also consider 
designing routines that trap timeout errors and empirically adjust the timeout pe- 
riod toward an optimum value. 


The alternative to specifying a timeout period is to use a value of TIMEOUT- 
—ASYNC when you call DdeClientTransaction. Doing this causes the DDEML to 
perform the transaction asynchronously. In this case, the call to DdeClientTrans- 
action returns immediately after the transaction is begun, and the DDEML saves 
the transaction in an internal queue until the server responds to it. For such asyn- 
chronous transactions, DdeClientTransaction returns a value that uniquely iden- 
tifies the transaction in the DDEML’s internal asynchronous-transaction queue. 
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When the transaction is completed, the DDEML notifies the client by calling its 
callback function. One of the parameters passed to the callback function con- 
tains the unique transaction-identifier value returned by the original call to 
DdeClientTransaction. 


There are two ways to abandon an asynchronous transaction before it is com- 
pleted. One way is for a client to call DdeAbandonTransaction. Another is for 
the transaction’s conversation to be terminated either by the server or by the cli- 
ent. In this case, the DDEML implicitly abandons all pending yan 
transactions for the terminated conversation. 


The fact that the DDEML supports both synchronous and asynchronous trans- 
actions implies a mechanism for DDE servers to use the DDEML to block trans- 
action processing transiently. While a server’s transaction processing is blocked, 
the DDEML queues asynchronous transactions until the server is unblocked. A 
DDE server can block transactions it receives in two ways. One is by calling 
DdeEnableCallback with a command code of EC_DISABLE. If you specify a 
conversation handle in the call to DdeEnableCallback, the DDEML blocks trans- 
actions only in the specified conversation. If you specify a null conversation 
handle, all conversations are affected. 


Another method of blocking transactions in a conversation is by returning a spe- 
cial value, CBR BLOCK, from the server’s callback function. Returning 
CBR_BLOCK places the transaction being processed in the callback function at 
the front of a queue and causes the DDEML to queue subsequent transactions 
in the conversation. Regardless of which blocking method you use, the server 
can unblock and begin to process queued transactions by calling 
DdeEnableCallback with a command code of EC_ENABLEALL (to process all 
queued transactions) or EC_ENABLEONE (to process only the first queued 
transaction). 


A server cannot block all types of DDEML transactions. A server callback func- 
tion can identify non-blockable transaction types by testing the XTYPF_NO- 
BLOCK flag, which is part of each transaction-type identifier. A server callback 
function should not return CBR_BLOCK for any transaction whose type identifier 
has the XTYPF_NOBLOCK flag set. 


DDE applications benefit greatly from the ability to combine asynchronous 
transaction processing with selective blocking of transactions. In particular, a 
server that needs time to do a prolonged computation or data transfer can tem- 
porarily block DDE transactions from clients until it completes the prolonged 
operation. For example, a database server might use DDE transaction blocking 
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to serialize requests for data so that successive database searches do not overlap 
or collide. A corresponding client application could issue its requests for data 
asynchronously so that a user’s interaction with the application could continue 
while the server performed a database search. 


The most important precaution in the use of asynchronous transactions and 
transaction blocking is to limit the amount of time that a server blocks incoming 
transactions. The size of the DDEML’s asynchronous-transaction queue is large 
but not infinite. Prolonged transaction blocking could overflow the queue or po- 
tentially overwhelm the server with unnecessarily repeated asynchronous 
transactions. 


The last two API functions that affect DDEML transaction management are 
DdePostAdvise and DdeSetUserHandle. A server calls DdePostAdvise to transfer 
updated data items to clients participating in data links. A client calls 
DdeSetUserHandle to associate an application-defined DWORD value with a 
specific asynchronous transaction. When the transaction is completed and the 
client callback function is notified, the client can retrieve the associated DWORD 
value through a call to DdeQueryConvInfo. 


String management 

The DDEML supports a string-management API that resembles Windows’ atom- 
manager API but provides more string-management options. An application calls 
DdeCreateStringHandle to obtain a handle (data type HSZ) that identifies a null- 
terminated character string. The inverse function, DdeQueryString, returns a 
copy of the string data and the length of the string associated with a particular 
string handle. 


The DDEML associates a usage count with each string handle. DdeCreateString- 
Handle initializes the usage count to 1. You can use two other DDEML API func- 
tions, DdeKeepStringHandle and DdeFreeStringHandle, to increment and 
decrement the usage count. If a string handle’s usage count is decremented to 0, 
the DDEML releases the memory in which the string is stored and invalidates the 
string handle. 


DDEML-aware programs must use string handles to identify DDE service, topic, 
and item names. However, you can also choose to use string handles for other 
purposes because string handles are easier to compare than the strings they rep- 
resent. For example, a single DDEML function, DdeCmpStringHandles, returns 
an integer that indicates the result of a case-insensitive comparison of the strings 
the handles represent. 
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Memory management 

The DDEML provides six important API functions that manage shared global 
memory on behalf of DDE servers and clients. DdeCreateDataHandle allocates 
a block of shared memory and optionally initializes it with data copied from a 
buffer. DdeCreateDataHandle returns a handle (data type HDDEDATA) that is 
used in the remaining DDEML memory-management functions and in many 
other DDEML API functions as well. 


A program can copy data from a private buffer into a shared memory block by 
calling DdeAddData. The inverse function DdeGetData copies data out of a 
shared memory block into a buffer. A program that needs only to read data from 
a shared-memory block without copying it can obtain a pointer to the data by 
calling DdeAccessData. Each call to DdeAccessData must be paired with a sub- 
sequent call to DdeUnaccessData, which invalidates the pointer returned by 
DdeAccessData. 


Although the DDEML memory-management API resembles Windows’ global 
memory-management API, there is an important difference in regard to freeing 
allocated memory. In Windows, each call to GlobalAlloc should be paired with a 
call to GlobalFree. With the DDEML, the rules are different. If you pass a data 
handle to a DDEML API function, the DDEML will free the associated memory 
block at the appropriate time. Similarly, you need not free data handles that the 
DDEML passes in parameters to an application’s callback function. 


There are only three situations in which a call to DdeFreeDataHandle is neces- 
sary. One is when an application allocates a memory block whose handle is 
never passed to a DDEML API function. Another is when a client receives a data 
handle as a return value from a call to the DdeClientTransaction function: The 
third is when a memory block is allocated with the HDATA_APPOWNED flag set 
in the call to DdeCreateDataHandle. Such memory blocks are owned by the ap- 
plication that creates them, so they can be reused indefinitely or in multiple DDE 
conversations. Because the DDEML does not automatically free these blocks of 
memory, it is the application’s responsibility to call the DdeFreeDataHandle 
function for them. 


The Callback Function 

The callback function in a DDEML application resembles a window function. 
Like a window function, a DDEML callback function is an exported PASCAL FAR 
function in which the first parameter identifies the kind of action the function is 
expected to carry out. In the following example, the EXPENTRY declaration 
defines DdeCallback as an exported PASCAL FAR function. 
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HDDEDATA EXPENTRY 

DdeCallback( WORD wType, WORD wFmt, HCONV hConv, 
HSZ hsz1, HSZ hsz2, HDDEDATA hDDEData, 
DWORD dwData1l, DWORD dwData2 ) 


The values represented in the callback function parameters vary according to 
the transaction type, as shown in Figure 6-11. . 


Transaction-Type Received Parameter Return Value 
Identifier 
XTYP_ADVDATA Client wFmt: clipboard data- Transaction 
Updates a data item ina format result flag 
data link hConv: conversation 

handle 


hsz1. topic name 

hsz2: item name 

hbDDEData: handle to 
data from server 


XTYP_ADVREQ Server wFmt: clipboard data- Handle to 

Requests updated data format updated 

item in a data link hConv: conversation data item 
handle 


hsz1: topic name 
hsz2: item name 


XTYP_ADVSTART Server wFmt: clipboard data- TRUE to start 

Initiates a data link format data link for 

(‘‘advise”) hConv: conversation the specified 
handle item 


hsz1: topic name 
hsz2: item name 


XTYP_ADVSTOP Server wFmt. clipboard data- 0 

Terminates a data link format 

C‘unadvise”) hConv: conversation 
handle 


hsz1: topic name 
hsz2. item name 


XTYP_EXECUTE Server hConv: conversation Transaction 
Requests command handle result flag 
execution hsz1: topic name 
bDDEData: command 
string 
Figure 6-11. (continued) 


Transaction-type identifiers and parameters for DDEML callback functions. 


Figure 6-11. continued 
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Transaction-Type 
Identifier 


XTYP_CONNECT 
Initiates conversation 


Server 


XT YP_CONNECT- 
—CONFIRM 
Confirms initiated 
conversation 


Server 


XTYP_XACT_COMPLETE Client 
Completes asynchronous 


transaction 


XTYP_POKE 
Transfers data item from 
client to server 


Server 


XTYP_REGISTER 
Indicates newly-registered 
service name 


Server, 
Client 


Received Parameter 


bsz1: topic name 

hsz2: service name 

dwDatatl: conversa- 
tion context 
(PCONVCONTEXT) 


bConv: conversation 
handle 

bsz1: topic name 

bsz2: server name 

dwData2: TRUE if 
same server and 
client instance 


wFmt: clipboard data- 
format 

bConv: conversation 
handle 

hsz1: topic name 

hsz2: item name 

bDDEData: handle to 
data from server 

dwDatazl: transaction 
ID 


wFmt: clipboard data 
format 

bConv: conversation 
handle 

hsz1: topic name 

hsz2: item name 

bDDEData: handle to 
data from client 


hsz1: service name 


bsz2: unique server- 
instance name 


Return Value 


TRUE to support 
a conversation 
on the speci- 
fied topic 


Transaction 
result flag 


0 


(continued) 
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Figure 6-11. continued 


Transaction-Type Received Parameter Return Value 
Identifier By 
XTYP_REQUEST Server wFmt. clipboard data _— Handle to re- 
Requests a data item format quested data 
hbConv: conversation 
handle 


hsz1: topic name 
hsz2. item name 


XTYP_DISCONNECT Server, hbConv: conversation 0° 

Confirms termination of Client handle 

a conversation 

XTYP_UNREGISTER Server, hsz1: service name 0 

Indicates unregistration of — Client hsz2: unique service- 

a service name instance name 
XTYP_WILDCONNECT Server hsz1: topic name or Handle to list 
Requests initiation of new a. wildcard of matching 
conversation(s) using wild- hsz2: service name or service-topic 
card specification wildcard names 


awDatal. conversa- 
tion context 
(PCONVCONTEXT) 


XTYP_MONITOR 

Used only in DDEML 
monitor applications; see 
the DDEML documentation 
for details 


You can design a DDEML callback function with a C-language switch statement 
whose cases correspond to the possible values of the transaction-type identifier. 
However, the structure of the DDEML transaction-type identifier lets you use 
other flow-of-control structures besides the switch statement in a DDEML 
callback function. 


The transaction-type identifier is actually composed of an index value combined 
with one of the flags shown in Figure 6-12. These flags classify each transaction 
according to the meaning of the value that the callback function is expected to 
return. 
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Flag Callback Function Returns 

XCLASS_BOOL TRUE or FALSE 

XCLASS_DATA Data handle CHDDEDATA) 

XCLASS_FLAGS Transaction result flag (DDE_FACK, 
DDE_FBUSY, or DDE-NOTPROCESSED) 

XCLASS_NOTIFICATION 0 

Figure 6-12. 


Transaction-class flags used in transaction-type identifiers for a DDEML 
callback function. The function returns a value of data-type HDDEDATA 
regardless of the meaning of the return value. 


There is an additional flag, XTYPF_NOBLOCK, that indicates whether a callback 
function can return CBR_BLOCK to block a transaction. For example, this is how 
the transaction-type identifier XTYP_CONNECT is defined in DDEML.H: 


#define XTYP_CONNECT (0x0060 {| XCLASS_BOOL ! XTYPF_NOBLOCK) 


In this definition, the value 0x0060 is an index value that uniquely identifies the 
transaction type. 


You can therefore structure a DDEML callback function according to the transac- 
tion class: 


switch( wType & XCLASS_ MASK ) 
a XCLASS_BOOL: 
ee 
case XCLASS_ DATA: 
peeek 
case XCLASS_FLAGS: 
ae 


case XCLASS_NOTIFICATION: 


break; 


} 
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You can also take advantage of the fact that the index values that are used in the 
transaction-type definitions follow a numerical sequence from 0x0000 through 
Ox00FO. This allows you to use a jump table instead of a switch statement to 
select among transaction-processing functions. The sample callback function in 
Figure 6-13 illustrates this technique. 


/* The following typedefs address the arguments to a DDEML 
callback function. The data structure maps the 
arguments as they appear on the stack according to the 
PASCAL parameter-passing convention.*/ 


typedef struct 
{ 


DWORD dwData2; 
DWORD dwDatat; 
HDDEDATA hDDEData; 
HSZ hsz2; 

HSZ hsz1; 
HCONV hConv; 
WORD wFEmt ; 
WORD wlype; 

} 
XACTPARAMS ; 


typedef XACTPARAMS * - PXACTPARAMS; 


typedef HDDEDATA (*PFNXACT) ( PXACTPARAMS ); 


/* prototypes for transaction-processing functions */ 


static HDDEDATA XactAdvdata( PXACTPARAMS ); 
static HDDEDATA XactXactComplete( PXACTPARAMS ) ; 
static HDDEDATA XactDisconnect ( PXACTPARAMS ) ; 
static HDDEDATA XactIgnore( PXACTPARAMS ); 
static HDDEDATA XactError( PXACTPARAMS ); 


/* jump table */ 
static PFNXACT pfnCallback[] = 
{ 


XactError, /* 00: XTYP_ERROR */ 
XactAdvdata, /* 01: XTYP_ADVDATA */ 
XactIgnore, /* 02: XTYP_ADVREQ */ 
XactIgnore, /* 03: XTYP_ADVSTART */ 
XactIgnore, /* 04: XTYP_ADVSTOP +*/ 
XactIgnore, /* 05: XTYP_EXECUTE +/ 
XactIgnore, /* 06: XTYP_CONNECT */ 
XactIgnore, /* 07: XTYP_CONNECT_CONFIRM */ 
Figure 6-13. (continued) 


Using a jump table in a DDEMEL callback function. 
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Figure 6-13. continued 


XactXactComplete, 
XactIgnore, 
XactIgnore, 
XactIgnore, 
XactDisconnect, 
XactIgnore, 
XactIgnore, 
XactIgnore 

}; 


/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


08: 
09: 
OA: 
OB: 
oc: 
OD: 
OE: 
OF: 
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XTYP_XACT_COMPLETE */ 
XTYP_POKE */ 
XTYP_REGISTER */ 
XTYP_REQUEST */ 
XTYP_DISCONNECT */ 
XTYP_UNREGISTER +*/ 
XTYP_WILDCONNECT */ 
XTYP_MONITOR */ 


[PERERA EERE EERE RHEE E EEE EERE ER EE RHEE HEHE EEE EEE EEE EEE EEE DEH HH 


* 


* DdeCallback 


* 


* 


* 


FH EEE EERE EERE EERE EHO H HEHEHE HOHE ERE E EEE HERE HEHEHE R OHO / 


HDDEDATA EXPENTRY 


DdeCallback( WORD wType, WORD wFmt, HCONV hConv, 
HSZ hsz1, HSZ hsz2, HDDEDATA hDDEData, 
DWORD dwDatal, DWORD dwDataz2 ) 


int nIindex; 


/* extract index value from transaction-type ID */ 
nIndex = (wType & XTYP_MASK) >> XTYP_SHIFT; 


/* jump through the table of function pointers */ 
return (*pfnCallback [nIndex]) ( (PXACTPARAMS) &dwData2 ); 


} 


Of the 15 transaction types used in DDEML callback functions, one (XTYP- 
_MONITOR) is used only in DDEML monitor applications such as DDESPY. Of 
the remaining 14, nine are reserved for servers only and two for clients only. The ° 
other three (XTYP_REGISTER, XTYP_DISCONNECT, and XTYP_UNREGIS- 
TER) are used in both server and client callback functions. You can design a 
callback function to process server transactions, client transactions, or both. In 
any case, remember to specify the appropriate command flags (APPCLASS- 
STANDARD with or without APPCMD_CLIENTONLY) when you call 
DdelInitialize to pass the callback function’s address to the DDEML. 
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XTYP_REGISTER and XTYP_UNREGISTER 


The DDEML uses these two transaction types to inform an application that an- 
other application has registered or unregistered a DDE service name. The pur- 
pose of these transactions is to alert DDE applications to the appearance or 
disappearance of services supported by DDE servers. 


XTYP_CONNECT, XTYP_WILDCONNECT, 
XTYP_CONNECT_CONFIRM, and XTYP_DISCONNECT 

A DDE server application’s callback function receives XTYP_CONNECT when a 
client attempts to initiate a conversation on a specified service and topic. The 
callback function should return TRUE (a nonzero value) if the server supports 
the specified service and topic. 


Similarly, a server receives XTYP_WILDCONNECT when a client wants to initi- 
ate conversations using a wildcard service or a topic specification. In this case, 
the server callback function must fill a block of shared global memory with an 
array of string-handle pairs (data type HSZPAIR) that enumerates service-topic 
combinations that match the wildcard specification. A null HSZPAIR indicates 
the end of the list. The return value from the callback function is the data handle 
(data type HDDEDATA) to the memory block containing the HSZPAIR list. 


Each time the DDEML successfully establishes a conversation, it calls the server 
callback function with a transaction type of XTYP_CONNECT_CONFIRM. With 
this transaction type, the DDEML passes a conversation handle (HCONV) that 
identifies the conversation in subsequent transactions, along with string handles 
that indicate the service and topic names for which the conversation was estab- 
lished. Although a server may save these handles for future reference, it is not 
strictly necessary to do so. The other callback-function transactions all provide 
these handles as function parameters whenever they are needed. 


The DDEML uses the XTYP_DISCONNECT transaction type to notify both 
server and client applications that a conversation has terminated. This trans- 
action type exists only for the convenience of the DDE application. A callback 
function should return a value of 0 in response to this transaction. 


Although the DDEML registers service names and passes string handles to ser- 
vice, topic, and item names as callback-function parameters, each DDE server 
and client application is responsible for maintaining its own lists of the service, 
topic, and item names that it supports. Use linked data structures to keep track of 
names so that you can easily associate a list of topic names with each service 
name supported by a server application. You can use the same technique to 
associate a list of item names and data pointers with each topic name. 
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XTYP_REQUEST and XTYP_ADVREQ 

A server’s callback function receives these two transaction types whenever the 
DDEML wants the server to transfer a data item to a client. A server receives 
XTYP_REQUEST when a client calls DdeClientTransaction to request data. The 
XTYP_ADVREQ transaction type is used when a server application calls 
DdePostAdvise to transmit an updated data item to a client in a data link. In both 
cases, the parameters passed to the callback function include the conversation 
handle, string handles to the topic and item names, and the clipboard data format 
for the requested data. The server callback function should return a data handle 
(HDDEDATA) to a shared memory block that contains the requested data. 


XTYP_POKE 


This transaction type notifies a server that an unsolicited data item has been 
transmitted from a client. The callback function parameters include a data 
handle for the shared-memory block that contains the data, the conversation 
handle, string handles to the topic and item names, and the clipboard data 
format. The server’s callback function must return a flag (DDE_FACK, 
DDE_FBUSY, or DDE_NOTPROCESSED) that indicates whether the server ac- 
cepted the data item. 


XTYP_EXECUTE 

The XTYP_EXECUTE transaction type is similar to XTYP_POKE. The differ- 
ence is that the data handle passed to the server’s callback function refers to a 
memory block that contains a null-terminated command string. The flag 
returned by the callback function (again, DDE_FACK, DDE_FBUSY, or 
DDE_NOTPROCESSED) indicates whether the server accepted the command. 


XTYP_ADVSTART and XTYP_ADVSTOP 

The DDEML calls a server callback function with XTYP_ADVSTART when a cli- 
ent attempts to start a data link with the server. The function parameters associ- 
ated with XTYP_ADVSTART include a conversation handle, string handles for 
the topic and item names for which the data link is requested, and a clipboard 
data format. The callback function must return TRUE if the server will support 
the requested data link. 


The XTYP_ADVSTOP transaction type notifies a server that a data link has been 
terminated by a client. The server application need not do anything in response. 
The callback function must return 0. 
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XTYP_ADVDATA and XTYP_XACT_COMPLETE 

These two transaction types are the only ones processed exclusively by client- 
application callback functions. The DDEML uses XTYP_ADVDATA to pass a 
data item from a server to a client in a data link. The XTYP_ADVDATA transac- 
tion type is just like XTYP_POKE. The callback-function parameters specify a 
conversation handle, topic and item names, a clipboard data format, and a data 
handle. The client callback function must return DDE_FACK, DDE_FBUSY, or 
DDE_NOTPROCESSED to indicate whether it accepted the data. 


The DDEML uses the XTYP_XACT_.COMPLETE transaction type to notify a cli- 
ent application that an asynchronous transaction has completed. When a client 
specifies TIMEOUT_ASYNC instead of a timeout period in a call to DdeClient- 
Transaction, the DDEML queues the transaction until the server is free to pro- 
cess it. The server’s response is always returned to the client through 
XTYP_XACT_COMPLETE, regardless of the type of transaction carried out. 


The function parameters associated with XTYP_XACT_COMPLETE include the 
usual conversation handle, string handles, and clipboard data type. The crucial 
parameter, however, is the first DWORD parameter, which contains the unique 
transaction identifier that was returned previously as a result value by 
DdeClientTransaction. 


The transaction identifer is important because the client can use it in a call to 
DdeQueryConvInfo, which fills a CONVINFO data structure with data that de- 
scribe the asynchronous transaction whose completion was signaled by 
XTYP_XACT_COMPLETE. Armed with the information in the CONVINFO data 
structure, the client callback function can carry out the same response to the 
completed asynchronous transaction as it might have if the transaction had been 
processed synchronously, as shown in Figure 6-14. 


Initiating a Conversation 


All of the DDEML callback-function transaction types make sense when you 
consider how they are used in relation to the DDEML API functions. For ex- 
ample, to initiate a conversation, a DDEML client calls DdeConnect or DdeCon- 
nectList. For each potential conversation—that is, for each service-topic pair 
requested by the client—the DDEML calls the appropriate server callback func- 
tion with an XTYP_CONNECT or XTYP_WILDCONNECT transaction type. 
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(called when a client receives XTYP_XACT_COMPLETE) */ 


HDDEDATA XactComplete( HCONV hconv, DWORD dwData1 ) 


{ 


} 


CONVINFO ci; 


/* Use the transaction ID to obtain information */ 
ci.cb = sizeof (CONVINFO) ; 
DdeQueryConvinfo( hConv, dwDatal, &ci ); 


/* Respond to completion of the asynchronous transaction */ 

switch( ci.wType ) 

{ 
case XTYP_ADVSTART: 
case XTYP_ADVSTART 
case XTYP_ADVSTART 
case XTYP_ADVSTART 


XTYPF_NODATA: 
XTYPF_ACKREQ: 
XTYPF_NODATA |} XTYPF_ACKREQ: 


peeak: 

case XTYP_ADVSTOP: 
Geode: 

case XTYP_EXECUTE: 
beenk: 

case XTYP_REQUEST: 
aay 

default: 


break; - 


} 
/* if an error occurred, display it */ 
if( ci.LastError ) 


DisplayErrorMessage( ... ); 


return 0; 


Figure 6-14. 

A client callback function calls DdeQueryConvInfo in order to process 
XTYP_XACT_COMPLETE. The transaction identifier is contained in the first 
DWORD parameter passed to the callback function (dwDatal). The original 
transaction type of the completed asynchronous transaction is found in wType 
in the CONVINFO data structure. 
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For each successfully initiated conversation, the DDEML passes a conversation 
handle to both client and server. The DDEML does this for the client through the 
return value from DdeConnect or DdeConnectList. On the server side, the 
DDEML calls the server’s callback function with an XTYP_CONNECT_CON- 
FIRM transaction type. 


Requesting Data from a Server 


To request data from a server, a client application calls DdeClientTransaction 
with a transaction type of XTYP_REQUEST. The DDEML calls the correspond- 
ing server’s callback function with XTYP_REQUEST. The data handle returned 
by the server gets back to the client in one of two ways. If the transaction is per- 
formed synchronously, the data handle appears as the return value from 
DdeClientTransaction. For an asynchronous transaction, the DDEML calls the 
client’s callback function with XTYP_XACT_COMPLETE, with the data handle 
as one of the callback-function parameters. 


Establishing a Data Link 


A client application establishes a data link by calling DdeClientTransaction with 
the XTYP_ADVSTART transaction type. The DDEML calls the server’s callback 
function with the same transaction type. If the transaction is synchronous, the 
server’s response is reflected in DdeClientTransaction’s return value. If the 
transaction is asynchronous, the client receives XTYP_XACT_COMPLETE from 
the DDEML. The client then checks wlastError in the CONVINFO data struc- 
ture to determine whether the data link was established. 


Sending Data to a Server 

A client sends a data item to a server by calling DdeClientTransaction and 
specifying the XTYP_POKE transaction type. The server’s callback function 
receives the data in an XTYP_POKE transaction. The DDEML returns the 
server’s response to the client either through the return value from 
DdeClientTransaction or through XTYP_XACT_COMPLETE and the wlastError 
value in the CONVINFO data structure. 


Executing a Command 


To execute a command, a client application calls DdeClientTransaction with the 
XTYP_EXECUTE transaction type. The server receives XTYP_EXECUTE and 
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returns DDE_FACK, DDE_FBUSY, or DDE_NOTPROCESSED, which the client 
receives either as a result value from DdeClientTransaction for a synchronous 
transaction or via XTYP_XACT_COMPLETE for an asynchronous transaction. 


Design Issues in DDE Applications 


The specifications for message-based DDE and for the DDEML API explicitly de- 
scribe the low-level transaction processing required in a DDE conversation. 
Nevertheless, there is more to designing a successful DDE application than sim- 
ply supporting a full set of DDE transactions. For example, two DDE applications 
must agree on the meanings of service and topic names, on what data formats to 
support, and on meaningful ways to specify and obtain results from executable 
commands. 


Selecting Service, Topic, and Item Names 


The DDE specification provides no guidance in choosing service, topic, and item 
names. Consequently, different applications use service, topic, and item names to 
represent different things. For example, Microsoft Excel uses an application 
name (Excel) as a service name, a spreadsheet name (Sheet) as a topic, and a 
spreadsheet cell identifier (RIC) as an item. However, an application that uses 
DDE to provide access to a relational database might use the service name to 
identify a database, the topic name to identify a database table, and item names 
to designate columns in the table. 


Two applications can establish a DDE conversation only if they agree on the 
meanings of service, topic, and item names. You should therefore accompany 
any DDE application you design with clear documentation of how the applica- 
tion uses service, topic, and item names. You can also automate the process to 
some extent by including support for the System topic in any DDE server appli- 
cation you design. Yet another approach is to design your DDE applications to 
use the clipboard to transfer service, topic, and item names to other DDE appli- 
cations, using the paste link method described in the DDE specification. 


In a DDE paste link, a server places a specified service, topic, and item name on 
the clipboard. A DDE client copies the names from the clipboard and uses them 
to initiate a conversation on the specified topic and a data link for the specified 
item. The server should format the service, topic, and item names as a sequence 
of three null-terminated strings, followed by an additional null byte: 


Service\0Topic\0Item\0\0 
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Both server and client applications should register the “Link” clipboard format 
and use it to access the service, topic, and item names on the clipboard. The 
server side of the paste link should be associated with a Copy command in an 
Edit drop-down menu. A client should use a Paste Link command in an Edit menu. 


Supporting the System Topic 


The Windows SDK documentation recommends that all DDE servers support a 
consistent set of data items under the System topic, as shown in Figure 6-15. 
These data items describe the topics supported by a DDE server. They can also 
provide a general indication of the server’s status. All the System data items use 
the CF_TEXT format, which makes it a bit easier for an application to describe a 
DDE server’s configuration or status to a human user. 


Item Name Description 


SysItems A list of items supported by the DDE server application under 
the System topic; for example 


"SysItems\tTopics\tStatus\tFormats" 


Topics A list of topics supported by the server 
Status Description of the current status of the server application; for 
example 
"Ready" 
and 
"Busy" 
Formats A list of clipboard data formats potentially supported by the 
server; for example 
"TEXT\tCSV\tLink" 
TopicltemList A list of items used by all topics except the System topic 
Help A string containing plain-text information that would help a 


user access the server application 


Figure 6-15. 
Data items supported under the System topic. All data items have the CF_TEXT 
format (null-terminated strings that use tabs as separators). 


200 


6: DYNAMIC DATA EXCHANGE (DDE) 


The Formats data item can be particularly useful to DDE client applications. A 
client application can parse the list of clipboard formats in this item to determine 
which clipboard format to specify in subsequent requests for data from a DDE 
server. There is one complication, however. When you design a DDE client to 
use the Formats item, the client must distinguish between the predefined clip- 
board formats, which have symbolic values defined in WINDOWS.H, and 
registered clipboard formats, which have values obtained from a call to 
RegisterClipboardFormat. 


By convention, a server represents the predefined clipboard formats with strings 
that correspond to the CF_ symbols defined in WINDOWS.H, but with the “CF_” 
prefix removed. (For example, a server indicates that it supports the CF_TEXT 
format by including “TEXT” in the Formats data item.) When a client parses the 
Formats item, it must test whether each format name is one of the predefined 
clipboard-format names. If it is, the client should use the corresponding CF_ 
value in WINDOWS.H; if not, the client should call RegisterClipboardFormat to 
obtain a clipboard-format value. 


Executing Commands 


The DDE specification defines a simple syntax for command strings used in a 
DDEML XTYP_EXECUTE transaction or ina WM_DDE_EXECUTE message. In 
this syntax, pairs of square brackets delimit individual commands. Commands 
themselves consist of alphanumeric verbs with optional comma-separated pa- 
rameter lists enclosed in parentheses. For example, the following DDE command 
sequence requests Microsoft Excel to display a message box and then beep. 


[alert ("Message from DDE client",2)] [beep(0)] 


These two commands could be sent from a DDE client to Excel either in a single 
DDE transaction or in a sequence of two separate transactions. 


The DDE specification is unclear about whether a command string can be 
associated with a particular topic. Traditionally, only the System topic responds 
to commands, but you may find it useful to execute commands in the context of 
conversations on topics other than the System. This allows applications to obtain 
different results by executing the same command for different topics. For ex- 
ample, imagine a database application in which a topic corresponds to a table in 
a relational database. A “select” command for this topic could implicitly refer to 
the particular database table represented in the topic; the same command for a 
different topic—that is, for a different database table—would produce a differ- 
ent result set. 
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There is an additional design problem in acknowledging WM_DDE_EXECUTE 
messages (with message-based DDE) or XTYP_EXECUTE transactions (with the 
DDEML). The problem arises because commands may take a long time to exe- 
cute. For example, a command might result in a server displaying a message and 
waiting for user input. In this situation, you must carefully consider how the 
server and client cooperate in acknowledging the command. 


If the server acknowledges receipt of the command when it receives it, the client 
can infer only that the command was successfully received. The client cannot 
assume that the command has actually been executed because the client might 
receive the server’s acknowledgement long before the server actually finishes 
executing the command. On the other hand, if the server defers acknowledg- 
ment until after it processes the command, the client might wait needlessly for a 
slow server to execute a command. 


One solution to this dilemma is for the server to support a special “Command 
Status” data item that contains the status of any command the server is execut- 
ing. Before posting any commands to the server, the client establishes a data link 
with the server for the Command Status item. Then, when the client posts a 
command to the server, the server can acknowledge receipt of the command di- 
rectly. When the server finishes executing the command, it can update the Com- 
mand Status item in the data link. The client can thus determine when a 
command has been successfully received and when it has actually been 
executed. 


Beyond DDE 


The DDE protocol, whether embodied in Windows messages or in the DDEML, 
is essentially a handshaking protocol for inter-application transfers of data. DDE 
makes it possible for applications to exchange multiple data items in an orderly 
way. DDE’s service/topic/item naming hierarchy is adaptable to a variety of 
data-exchange scenarios, including network communications and database 
applications. 


Nevertheless, DDE is not a good tool for binding different applications together 
interactively. Doing so requires you to know low-level details about the applica- 
tions you use, including service, topic, and item names or registered clipboard 
formats. You also must know how to access DDE through the applications you 
are using. For example, if you are using Microsoft Excel, you must understand 
Excel’s macro language as well as DDE. A higher-level approach to interprocess 
communication would be better than DDE for many Windows users. 
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Microsoft’s approach to supporting high-level interprocess communication is a 
protocol called Object Linking and Embedding (OLE). Unlike DDE, which is de- 
signed to support data transfer between applications, OLE supports functional 
links between documents such as spreadsheets, charts, or word processing 
documents. You can think of an OLE document as a compound document that 
can contain any number of different data objects, each of which is associated 
with an application that can be used to edit it. From a Windows user’s point of 
view, such functionality is much more intuitive than that supported in DDE. 


The “linking” part of OLE refers to dynamic links between data objects in an 
OLE document and the applications that manipulate the data objects. For ex- 
ample, a Windows user can use the mouse to click on a linked data object in a 
compound document and thereby execute the application with which the data 
can be edited. In contrast, “embedding” refers to storing a data object in a com- 
pound document without maintaining a dynamic link to another application. 


From a programmer’s perspective, a choice between OLE and DDE depends on 
what functionality an application is designed to support. For low-level data trans- 
fers that do not require direct intervention, DDE is an appropriate choice. For 
high-level, user-controlled data links between Windows applications, you should 
consider using OLE. 
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7: PROBLEMS AND SOLUTIONS 


This chapter is a collection of Windows programming techniques. All are “ad- 
vanced” in that they make more sense when you are comfortable programming 
in the Windows environment, but none are tricks or secrets. Everything is based 
on an understanding of how things work in Windows. 


Control Variations 


The built-in control classes—particularly the list-box, edit, and combo-box 
classes—provide a great deal of ready-to-use functionality. Many good Win- 
dows applications rely entirely on the predefined control classes. 


Nevertheless, the predefined control classes don’t do everything. If you want a 
control that looks like one of the built-in control classes but that behaves some- 
what differently, you must decide whether to build a look-alike variation from 
scratch as a custom control or to work with a built-in control and add the func- 
tionality you need. 


Controls with Thick Frames 


Imagine that you want to design a list-box control with a title bar and fat borders 
that let the user move and size the control. You might suppose that you could use 
the WS_CAPTION, WS_SYSMENU, and WS_THICKFRAME window styles to 
create such a window. For example, the list box shown in Figure 7-1 on the fol- 
lowing page can be created by using the following CreateWindow call: 


CreateWindow( "ListBox", 
"Popup ListBox", 
WS_CAPTION |! WS_POPUP ! WS_THICKFRAME } 
WS_SYSMENU | WS_VSCROLL ! WS_VISIBLE, 
200, 200, 200, 200, 
hWnd, 
0, 
hInstance, 
NULL ); 


The problem with this technique is that all the predefined control classes do not 
work properly with all possible window styles in all versions of Windows. The 
predefined controls were not designed to be resized or to serve as pop-up win- 
dows. You may find that windows such as the pop-up list box shown in Figure 
7-1 do not flash when they receive the focus or fail to draw their non-client areas 
properly. Figure 7-1 is a case in point—the list-box class window function in 
Windows 3.0 has ignored the WS_THICKFRAME and WS_CAPTION styles and 
made the client area too small, incorrectly clipping the last item in the list box. 
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ea Popup siBo 
This is item 0 
This is Item 1 
This is item 2 
This is item 3 
This is Item 4 
This is item 5 
This is item 6 
This is item 7 
em 9 


This is itern 9 


Figure 7-1. 
A list-box control with the WS_THICKFRAME and WS_CAPTION styles. 


A more reliable way to support a control with a caption bar or a thick frame is to 
frame the control in a parent window that has the desired window style. The 
parent can process WM_SIZE messages to size the-child-window control appro- 
priately within the parent’s client area. All predefined control classes respond 
properly to WM_SIZE messages, so the parent can call the MoveWindow function, 
which sends a WM_SIZE message, to control the size of a child-window control. 


Figure 7-2 shows how to use this method. The top-level window in the applica- 
tion is the parent of an edit control. The top-level window function, TopLevel- 
WndFn, processes the WM_SIZE message by calling MoveWindow to resize the 
edit control. The parent-child combination has the visual appearance of a single 
edit-class window that can be moved and sized. 


HHH Reese eee oweeeesenatesne REEHHREEHHHREESHEREEDEDERAESOERESEHORESSEREES SE RERE HE ne 


# NMAKE description for OVEDIT.EXE coe ea ars 


Hee oeeeeseeeesesneeneHweee FHREREEHHREHHHERERFHAREREHOEEFHAHEFHFHREEHHHERESHREED 


-c.obj: 
el /BM Io /G2sw ‘/osw 144 /Z1p §$*.c 


ALL: Se ovedit exe 
ovedit. obj: ovedit.c 
ovedit.exe: ovedit. obj ovedit . . det 


link /al:16 /nod Lee Latches , 1 libw mlibcew, ovedit. det ee 
re ovedit.exe ae 


Figure 7-2. (continued) 
Source code for OVEDIT.EXE.. 
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Figure 7-2. continued 


[REE EERE EERE EEE REE E EEE ERE E EERE REE E REET ERE R EERE E HHT H EEE EE EEE 


* * 
* OVEDIT.C * 
* . * 
* Exports: TopLevelWndFn . 
* # 


PEPER ERTS EERE ERE R ESHER EE ETRE EEE EP THERE PEER SERRE EE EERE E EERE R RHE R EEE HE EEE / 


#define NOCOMM 
#include <windows.h> 


#define IDEDIT 100 


/*** FUNCTION PROTOTYPES *+*/ 
LONG PASCAL FAR TopLevelWndFn( HWND, WORD, WORD, LONG ); 


static HWND Init ( HANDLE, HANDLE, int ); 


/*** GLOBAL VARIABLES *+*+/ 


char szTopLevelClass[] = "OvEdit:TopLevel"; 


[PERRET EEE EERE EE EERE EEE E EEO E REE SEER EE EER EERE EERE SEER EEE ER EEE EEE RETR EE EE 


* * 
* WinMain is * 
* * 


HAE E REESE REE E EEE EE REE TEEPE RARER TEAR TEAS RARER ERPS EERE EERE RR RHR R EE REE EER / 


int PASCAL 
WinMain( HANDLE hInst, HANDLE hPreviInst, LPSTR lpszCmdLine, int nCmdShow ) 


{ 
HWND “hWnd; 
MSG msg; 


hWnd = Init( hInst, hPrevInst, nCmdShow ); 
if( thWnd ) 
return 0; 


(continued) 
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Figure 7-2. continued 


while( GetMessage( smsg, 0, 0,0)) _ 
{ pees 
TranslateMessage( &msg ); 
DispatchMessage( &msg ); 
} 


return msg.wParam; 


[RHEE TERETE REE E TERE EE TEER ESSE SERFS HERES OPERAS TR EFEH TREE HO REET HEE RESET EEE HEE E : 


* : ; : Cea 
* Init « 
* : : * 


SENHA DEE HEE ETO ERD RD RHEE REO OS ER EEE ETERS EDD EE HERO OE HERDER EERE OH ERR E OEE aH EE HED / 


static HWND Init( HANDLE hInst, HANDLE hPrevinst, int nCmdShow ) 
ceaaen ecrepametehtre dues 

WNDCLASS we; 

HWND hWnd; 


if( 0 == hPreviInst ) 
/* register the top-level window class af: 
we.lpszClassName = szToplevelClass; Bo 


Hl 


we. hInstance =hinst; | Rerisens 28 

we. lpfnWndProc =: TopLevelWndFn; SAB bs 

we. hCursor = LoadCursor (_ 0; IDC. ARROW ); 

we. hIcon = LoadIcon (_ 0, wr APPLICATION ): 
we.lpszMenuName = NULL; : 

we /hbrBackground: = COLOR_! WINDOWH; 

we. style 208 HREDRAW | " CS_VREDRAR; 
we.cbClsExtra = 0; : Bee OSES SO 
we.cbWndExtra = 0; _ 


if( !Register Class( &we ) ) Raa : 
return 0; | /* return 0 if unsuccessful */ — 


ot 


_ /* ereate the top-level window */ 
hWnd = CreateWindow( szTopLevelClass, 
"OvEdit", 
WS_OVERLAPPEDWINDOW, Lie. 
CW_USEDEFAULT, 0, CW eUPEDEEAULE, 0, 
sa 


(continued) 
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Figure 7-2. continued 


return hWnd; 
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0, 
hInst, 
NULL ); 


/* create the edit control +/ 
CreateWindow( "Edit", 


a 
‘ 


WS_CHILD | WS_VSCROLL ! WS_HSCROLL | WS_VISIBLE ! 
ES_MULTILINE, 

0, 0, 0, 0, 

hWnd, 

IDEDIT, 

hInst, 

NULL ); 


/* display the top-level window */ 
ShowWindow( hWnd, nCmdShow ); 
UpdateWindow( hWnd ); 


[REE EE EERE EE ERE EEE EEE REE REET EERE EE TEETER SEETHER EERE EE EEE EERE EEE HEHEHE 


* 


* TopLevelWndFn 


* 


* 


* 


HH HREE RENE EEE HERE E EERE ERE RHEE EERE HERES ER EA RETA R EEE HERE E HERES E HERE EERE REE EH / 


LONG PASCAL FAR 


TopLevelWndFn( HWND hWnd, WORD wMsg, WORD wParam, LONG 1Param ) 


{ 


1RVal = OL; 
bDWP = FALSE; 
switch ( wMsg ) 


case WM_SIZE: 
MoveWindow( GetDligItem( hWnd, IDEDIT ), 


0, 0, 
LOWORD (1Param), HIWORD (lParam), 
FALSE); 


(continued) 
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Figure 7-2. continued 


case WM_SETFOCUS: tee 
SetFocus ( GetDlgitem( hWnd, _IDEDIT ') : 
break; 


case WM_DESTROY: 
PostQuitMessage( 0 Le 
break; 


default: 
DDWP. =. TRUE; 
break; 
} 


if( DDWP >) 
1RVal = DefWindowProc( hWnd, wMsg, wParam, lParam ); 


return 1RVal; 


FRAO HEREEEHEREEH HEE EEHERRE THERE HAE EEH ERE EEE HERES HREHOHHEEEEEHEREEHEEREEE ERATED 
: ° : * 
eed 
o 7 QVEDIT.DEF module-definition file. : 
Babette f ; * 
, 
PRM EREHHERERHE REDS EH AEREHE REND EEEREAPHERESHOREREFEEEEHHHEEERH EEE EHEREED EE RES ESE 


NAME OVEDIT 


DESCRIPTION ‘OVEDIT.EXE version 1.0' 
EXETYPE | —« WINDOWS 
STUB 'WINSTUB. EXE! 
CODE = ~—s MOVEABLE LOADONCALL DISCARDABLE 
DATA MOVEABLE MULTIPLE PRELOAD 
SEGMENTS TEXT MOVEABLE PRELOAD DISCARDABLE 
HEAPSIZE 1024 
STACKSIZE 5120 
EXPORTS — TopLevelWndFn 
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You need not force the size of the child-window control to equal the size of the 
parent’s client area. You might instead hide the child-window control whenever 
the size of the parent’s client area reaches a predefined threshold. You could also 
keep the control’s size proportional to the size of the parent. Windows’ Notepad 
application illustrates this technique, as shown in Figure 7-3. In Notepad, the size 
of the edit control is somewhat smaller than the size of the parent’s client area. In 
this way, Notepad maintains a visible margin between edited text and the edge 
of the parent window. As you change the size of the parent, Notepad resizes the 
edit control to maintain the margin. 


= fee ae oss Notepad = HELLO,C 


file Edt Seach Hep 


ello.c 
Hello Application 

Windows Premiere Edition 
Copyright (c) Microsoft 1985 


Minclude ‘windows .h" 
include "hello.h" 


har *szAppNane ; 

har *szAbout; 

har *szWindowTitle; 
nt TitleLength; 


static HANDLE hInst; 
-RRPROC 1pprocAbout ; 


ong FAR PASCAL HelloWndProc(HWND, unsigned, WORD, LONG); 


ROOL FAR PASCAL About(¢ hD1lg, message, wParam, 1Param ) 
iWND hD1lg; 

nsigned message; 

ORD wParan; 


Figure 7-3. 
In Notepad, the edit control (outlined in black) is always somewhat smaller 
than its parent window’s client area. 


Another way to create variations of the predefined control classes is to use mes- 
sage filtering or subclassing. The only problem with this approach is that 
Microsoft does not document how specific messages are processed by each of 
Windows’ predefined control classes. This means that a message-filtering tech- 
nique that works in the current version of Windows might fail in a future version 
should Microsoft change the way predefined control classes process messages. 
Nevertheless, the technique is powerful and well worth investigating if your ap- 
plication requires only a simple variant of one of the predefined controls. 
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For example, you can design read-only versions of the default edit, list-box, and 
combo-box controls by trapping the keyboard and mouse messages that are nor- 
mally processed by the controls’ window functions. By blocking normal key- 
board and mouse input, you create controls whose contents cannot be changed 
interactively. 


The source code for ROEDIT.DLL, in Figure 7-4, defines a read-only variation of 
the default edit control class. The read-only class is named ROEdit. You can use 
ROEdit controls just as you would use edit controls. The only difference is that 
you must be certain to load ROEDIT.DLL with a call to LoadLibrary before you 
create any ROEdit controls, as shown in Figure 7-5 on page 220. 


RPAH EET EEE ERH ERE E HEE EE ETE ERE EEE E ETHER EEE SORES ERE EERE TEETER RES HEHE REET ESS 


# * 
# NMAKE description for ROEDIT.DLL . 
# * 


PERERA EERE ERE R EH EE EERE HERE HORE EERE E EEE OR ESTHER EEE ESHER EEE ERE EEE OEE ERE EES 


.¢.0b3: : ee 
cl /AMw /c /D WINDOWS /D _WINDLL /G2sw /Osw /W4 /Zlp $*.c 


ALL: roedit.dil 


init.obj: init.c roedit.h 

roedit .obj: roedit.c roedit .h 

wep.obj: wep.c 

roedit.dll: init.obj roedit.obj wep.obj roedit.def 


link /al:16 /nod /noe libentry init roedit wep, roedit.dll, , \ 
libw mdllcew, roedit.def 
ae ee yao ee DIOP ongh s fe Bede SURE 


Figure 7-4. (continued) 
Source code for ROEDIT.DLL. 
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Figure 7-4. continued 


[HERR DHE RET EH ERED ETERS HERES HEREFSSEEESSERFE REFER ESHER EFOEOEESOERER SHH EH ERLE 


r . 
* INIT.C . 
* * 


ee ee 


#define NOCOMM 
#include <windows.h> 
#include "roedit.h" 


/*** GLOBAL VARIABLES ***/ 


HANDLE hDLLInst; 
FARPROC pDefEditWndFn ; 
static char szROEditClass[] = "ROEdit"; 


/*** FUNCTION PROTOTYPES ***/ 
BOOL PASCAL FAR LibMain( HANDLE, WORD, WORD, LPSTR ); 


static BOOL RegisterEditSubclass( HANDLE ); 


LAPP ERE EERE TREES TEESE TERETE EERE TESTER HSER ES EERE SEP ERE E TERRE ESHER EERE HEED EE EE 


® * 
* LibMain * 
* * 


HERES H EHP SEER E SHEEP ARPES ESE RETEST E SAE RHESE EEE E REE E ERR HRE ERE HEHE REE E ERE E EE / 


BOOL PASCAL FAR 
LibMain( HANDLE hInst, WORD wDS, WORD wHeapSize, LPSTR lpCmdTail ) 


{ 
BOOL = bRVal; 


/* if LibEntry has called LocaliInit, unlock the default data segment */ 
if ( wHeapSize ) 
UnlockSegment ( wDS .) ; 
/* save the DLL instance handle in a global variable */ 
hDLLIinst = hinst; 


(continued) 
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Figure 7-4. continued 


/* register window classes */ 
bRVal = RegisterEditSubclass( hinst ); 


return bRVal; 


[HERE ERE EE EERE TEER REE EERE EH EERE EEE EREERE EERE EERE SERE EEE ERUEREREEH EERE EEE ED 


* * 
* RegisterEditSubclass * 
* Returns TRUE if the filter function is successfully registered. . 
+ 7 + 


HHH RRER ERE EERE HEED EEE EEE EEE EEEE RENEE ER ESE ETHER EERE HERERO H ESSE RRR E HERE E EEE / 


static BOOL RegisterEditSubclass( HANDLE hLibInst ) 


{ 
BOOL bRVal = FALSE; 
WNDCLASS wc; 
if( hLibInst ) 
{ 
/* get default WNDCLASS values for the edit class */ 
GetClassInfo( 0, "Edit", &we ); 
/* save the address of the edit class window function */ 
pDefEditWndFn = (FARPROC) wc.lpfnWndProc; 
we. hInstance = hLibInst; 
we. lpszClassName = szROEditClass; 
we. lpfnWndProc = ROEditWndFn; 
we.style i= CS_GLOBALCLASS; 
bRVal = Register Class( &we ); 
} 
return bRVal; 
} 


(continued) 
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Figure 7-4. continued 


[RARE EERE AREER EE EEE EEE EERE EEE E EET EERE EERE EEE HERE E DERE EEE H EEE RHR EH 


* * 
* ROEDIT.C * 
* * 
* Exports: ROEditWndFn * 
* * 


REPRE HERE EEE EH EE ERE E SORE TEAR ETHER EERO E EEE E HER RHE R EERE RHEE ERED EH REE ED / 


#define NOCOMM 
#include <windows.h> 
#include “roedit.h" 


/*** FUNCTION PROTOTYPES ***/ 


static void MsgKeyDown( HWND, WORD ); 


/*** GLOBAL VARIABLES ***/ 


extern FARPROC pDefEditWndFn; /* (defined in INIT.C) */ 


[REE EERE REE E ETRE EERE RHEE ERE E EERE RETR ERE STEERER ERE ER ERE E RTE E EERE EE EERE EE 


* ROEditWndFn * 
* : * 


FERRER EEE EERE HEEE HERE REA ETE EEE EEE SERRE SER ESTHER EE HEHE ERE RE REE RHEE ERE EEE EH / 


LONG PASCAL FAR 
ROEditWndFn( HWND hWnd, WORD wMsg, WORD wParam, LONG lParam ) 
{ 

LONG 1RVal = OL; 

BOOL bCWP = FALSE; 


switch( wMsg ) 
{ 
case WM_KEYDOWN: /* trap all these messages */ 
case WM_CHAR: 
case WM_MOUSEMOVE: 
case WM_LBUTTONDOWN: 
case WM_RBUTTONDOWN: 
case WM_RBUTTONUP: 


(continued) 
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Figure 7-4. continued 


case WM_MBUTTONDOWN: 
case WM_MBUTTONUP: 
break; 


case WM_SETCURSOR: /* trap client-area messages */ 
bCWP = (LOWORD( 1Param.) != HETCLIENT) ; 
break; 


default: 
DCWP = TRUE; 


break; 


} 


if ( BCWPR ) 
1RVal = CallWindowProc( pDefEditWndFn, hWnd, wMsg, wParam, lParam ); 


return 1RVal; 


[PEER E REE E EEE EEE REHEAT DEERE EE HEE EE HARROP THRESH EEREEHHERESEOREEEOREERE EER EH 


* * 
* WEP.C : 
* * 
* Exports: WEP RESIDENTNAME . 
» * 


FHEREREERERRHREE OEE ER ESE RHR EE HEE R EER ERHEEH RE ODEFEHESEREREEHEFES SEDER TEER OR EES / 


#define NOCOMM 
#finclude <windows.h> 


/*** FUNCTION PROTOTYPES ***/ 


int PASCAL FAR WEP( int ); 


(continued) 


218 


7: PROBLEMS AND SOLUTIONS 


Figure 7-4. continued 


[RAPER REET EEE E HEHE TEE EEE ESET HEE ETERS EEE EE EEE EET EDR RETR EE DEERE HOE EERE HD 


* * 
* WEP * 
* + 


itt tt ee 


int PASCAL FAR WEP( int nParam ) 
{ 


return 1; 


} 


[RARER RHEE EEE REESE EERE EERE EE ERE EH EEE EERE ARETE EEE EEE RE ESET ERE EERE EERE ED 


* ROEDIT.H . 
# * 


FERRE ETHER EEE EET TER EEAEE FET EE SEER EE EFE SETHE HERE ER HEE e EEE RR ERE TEER REE / 


/* defined in ROEDIT.c */ 
LONG PASCAL FAR ROEditWndFn( HWND, WORD, WORD, LONG ); 


POOUSUSCICSICOCOOOSSOOIICTOSSICOCT Til ir reli irs i itiri irr titi reir irri iirc iicy, 
° : * 
tA 

;. ROEDIT.DEF module-definition file * 


be ? 
’ 
PSSA EEN SELES E TE EE ERIS ERE E REREAD EHERE SEERA EEO EE ERE HE HEE EA EO ESOEE EEE SEO EGE ESS OES 


LIBRARY. ROEDIT 
DESCRIPTION "ROEDIT version 1.0' 
EXETYPE WINDOWS 


CODE LOADONCALL MOVEABLE DISCARDABLE 
DATA PRELOAD MOVEABLE SINGLE 


HEAPSIZE 0 


SEGMENTS INIT_TEXT PRELOAD DISCARDABLE 
WEP_TEXT PRELOAD FIXED 


EXPORTS WEP @1 RESIDENTNAME 
ROEditWndFn @2 
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int PASCAL 
WinMain( HANDLE hInst, HANDLE hPrevInst, 
LPSTR lpCmdLine, int nCmdShow ) 
{ 
HWND hWnd; 
MSG msg; 
HANDLE hDLL; 


/* load the library and verify the returned handle */ 
hDLL = LoadLibrary( "ROEDIT.DLL" ); 
if( hDLL < 32 ) 

return 0; 


/* continue with the usual Windows processing */ 
hWnd = Init( hInst, hPrevInst, nCmdShow ); 
if( !hwWnd ) 

return 0; 


while( GetMessage( &msg, 0, 0, 0) ) 
{ 
TranslateMessage( &msg ); 
DispatchMessage( &msg ); 
} 


/* free the library */ 
FreeLibrary( hDLL ); 


return msg.wParam; 


} 


Figure 7-5. 
Loading and unloading the ROEDIT.DLL library in an application that uses the 
ROEdit class. 


ROEdit is implemented by filtering keyboard and mouse messages before they 
are processed by the default edit-class window function. The function ROEdit- 
WndFn passes all other messages unchanged to the default edit-class window 
function, whose address is stored in a global variable by the RegisterEditSubclass 
function when the DLL is initialized. 


The subclass window function, ROEditWndFn, looks straightforward, but ac- 
tually a bit of magic is involved in its construction. Microsoft does not document 
how the default edit control’s window function processes messages. In the case 
of ROEditWndFn, the magic lies in the ad hoc assumption that the way to create 
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a read-only control is to trap all keyboard and mouse input messages. This seems 
reasonable, but you must actually try it to be sure that the default edit-class win- 
dow function is not carrying out some invisible, yet essential, action in response 
to one of the messages trapped in ROEditWndFn. 


Owner-Draw Controls 


Another technique for wringing new functionality out of the predefined control 
classes is to use owner-draw control styles. Owner-draw controls appeared in a 
somewhat different form in OS/2 Presentation Manager before they were in- 
troduced in Windows version 3.0. In Windows, owner-draw styles are supported 
for list-box, combo-box, and button controls, as well as for menus. The principle 
behind owner-draw controls is simple: Whenever Windows wants to change the 
appearance of a control with an owner-draw style, it sends a WM_DRAWITEM 
message to the control’s owner—that is, its parent window. It is then up to the 
owner to redraw the control using the appropriate data, font, graphics, or colors. 


Processing the WM_DRAWITEM Message 


Owner-draw controls are valuable because they let an application determine 
both the appearance and the actual data displayed for each item in a control. An 
owner-draw control accomplishes this by sending a WM_DRAWITEM message 
to its owner for each item to be displayed. Each WM_DRAWITEM message is 
associated with a DRAWITEMSTRUCT data structure, which contains a 4-byte 
value (itemData) that identifies the data item to be displayed. How you use item- 
Data depends on the application— itemData might contain a pointer to a string 
for text data, an RGB value for a color, or a handle to a GDI object. The DRAW- 
ITEMSTRUCT also contains a device-context handle (bDC) and an update rect- 
angle (rcltem) so that the owner can update the appropriate part of the control’s 
client area. 


A key element in each WM_DRAWITEM message is a set of flags contained in 
two variables in the DRAWITEMSTRUCT structure. These flags indicate whether 
a data item needs to be repainted in its entirety or whether the data item should 
be repainted to reflect its selection status or a change in focus. The itemAction 
flags, shown in Figure 7-6 on the following page, inform the owner of an action 
that has changed the state of a data item. The itemState flags, shown in Figure 
7-7 on the following page, describe the new state of the item. The owner should 
refer to the itemAction and itemState flags to redraw the data item so that its vi- 
sual appearance reflects its new state. 
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Flag Meaning 

ODA_DRAWENTIRE The entire data item needs to be redrawn. 

ODA_FOCUS The data item needs to be redrawn to indicate that the 
control has gained or lost the input focus. 

ODA_SELECT The data item needs to be redrawn to indicate that it has 


been selected or deselected. 


Figure 7-6. 
Flags defined in the itemAction field in a DRAWITEMSTRUCT data structure. 


Flag Meaning 
ODS_CHECKED The menu item is checked 
ODS_DISABLED The control is disabled 
ODS_FOCUS The control -has the focus 
ODS_GRAYED The menu item is grayed 
ODS_SELECTED The data item is selected 
Figure 7-7. 


Flags defined in the itemState field in a DRAWITEMSTRUCT data structure. 


The owner must also determine what data to display each time it processes a 
WM_DRAWITEM message. The itemID variable in the DRAWITEMSTRUCT 
structure contains an index value that indicates a data item’s position in an 
owner-draw control or menu. For list-box and combo-box controls, the item- 
Data value specifies the data item to display. An item’s itemData value is deter- 
mined at the time the item is first added to the control with a CB_ADDSTRING, 
LB_ADDSTRING, CB_INSERTSTRING, or LB_INSERTSTRING message. 


It is easy to build an owner-draw control with an unusual appearance because 
the owner determines exactly how each data item is displayed. For example, you 
could build an owner-draw button that displays two custom bitmaps, one when 
the button is pressed and another when it is not. You could also design a read- 
only list box control by using an owner-draw list box that does not highlight the 
currently selected item. 
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Owner-draw controls let you build list-box and combo-box controls that let the 
control’s owner directly manage the list of data items displayed in the control. 
You can use this technique to design controls that display data other than null- 
terminated strings. You can also build controls that display more data than can 
be handled by Windows’ built-in list box and combo box list-management 
routines. 


Imagine, for example, that you want to use a list-box control to browse a data- 
base of 5,000 items. Without using the owner-draw style, 5,000 items probably 
represents more data than the list-box control can manage because the amount 
of memory the control can use to store its data is limited. (The limit is a little less 
than 64 KB in Windows 3.0.) With an owner-draw style, however, the control 
can avoid this memory limitation by storing 4-byte data-item identifiers instead 
of storing actual string data. When Windows sends the control’s owner a 
WM_DRAWITEM message, it uses the itemData value in the accompanying 
DRAWITEMSTRUCT data structure to identify the string to display. 


The source code for ODLB.EXE, in Figure 7-8, shows how this is done. Each time 
the application sends an LB_ADDSTRING message to the list box, it specifies a 
4-byte numerical identifier instead of a string pointer. When the application pro- 
cesses WM_DRAWITEM messages, it uses the 4-byte identifiers to synthesize 
data strings on the fly. In a real Windows program, however, the strings might be 
obtained from an application-specific source such as a database-management 
system by using the itemData value to identify unique items. The sample appli- 
cation emulates the default appearance of a list-box control by using PatBit and 
DrawFocusRect in response to the itemAction and itemStatus flags, but this too 
could be changed to meet the specific needs of a real application. 


EMRE RE EEE HH EERE HERES TERRE EER ERE EERE EEE REE HEHE EER EERE REEF STEERER HED DH 


# : * 
# NMAKE description for ODLB.EXE . 
# + 


FRA HARE H EERE EERE EEE EEE RE DERE RE HEE EEE ERE EE HEE EEE EERE EERE REPRE EEE E DEH E EE HEE EE 


-¢.0bj: 
cl /AM /c /G2sw /Osw /W4 /Z1lp $*.c 


Figure 7-8. (continued) 
Source code for ODLB.EXE. 
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Figure 7-8. continued 


ALL: odlb.exe 


odlb. obj: odlb.c 
odlb.exe: odlb.obj odlb.def 


link /al:16 /nod /noe odlb, , , libw mlibcew, odlb.def 
re odlb.exe 


[RARER EEE REET HERE HER EEE HEE EE EERE PEER EE EERE EE EERE EEE RHEE EH ERATE H EERE ER EEE 


* * 
* ODLB.C * 
* * 
* Exports: TopLevelWndFn i 
? * 


FH EREEE RHE REH EEE E HERE REE HER ER ERE EEE PEER EEN EERE EERE REESE ROR E HERE ERE RRR EERE ERE / 


#define NOCOMM 
#include <windows .h> 


#define IDLISTBOX - 0x1000 

#define IMAX 5000 

/*** FUNCTION PROTOTYPES ***/ 

LONG PASCAL FAR TopLevelWndFn( HWND, WORD, WORD, LONG ); 


static HWND Init ( HANDLE, HANDLE, int ); 


static void MsgCommand ( HWND, WORD, LONG ); 
static void MsgDrawltem( HWND, LPDRAWITEMSTRUCT ); 


/*** GLOBAL VARIABLES ***/ 
char szTopLevelClass[] = "ModStat:TopLevel"; 


char _— szAppTitle[] = "Owner-Draw ListBox"; 
HANDLE hInstance = 0; 


(continued) 
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Figure 7-8. continued 


[HERR EEE EER RENTER EERE ERATE EEE HERE H ERE E EERE ETHER EEE EE ORE E HERE THERE HEE EE 


* * 
* WinMain * 
* e 


FHRHEEE EERE EES A EEE E ERE P EERE ERE TREES REET ERE ER HERE RETR REE H EEE E EEE EERE EEE / 


int PASCAL 
WinMain( HANDLE hInst, HANDLE hPrevInst, LPSTR lpszCmdLine, int nCmdShow ) 


{ 
HWND hWnd; 
MSG msg; 


hWnd = Init( hInst, hPrevInst, nCmdShow ); 
if( !hWnd ) 
return 0; 


while( GetMessage( &msg, 0, 0, 0) ) 
{ 
TranslateMessage( &msg ); 
DispatchMessage( émsg ); 
} 


return msg.wParam; 


[PER REE REE R EEE REE REESE HE EEE EE ER EER EE EEE HATES EERE EERE EERE EERE EERE EEE EERE EHH EH 


* + 
* Init . 
* + 


PEPER EERE RHEE ESHER PES FRESE REE EE EEE REE SEHR EES E REE SEER REE R HEHEHE RES EO REE HEE / 


static HWND Init( HANDLE hInst, HANDLE hPrevInst, int nCmdShow ) 


{ 
WNDCLASS — we;; 


HWND hWnd, hListBox; 
int n; : 
LONG 1RVal; 


if( 0 == hPrevinst ) 


{ 
/* register the top-level window class */ 
we.lpszClassName = szTopLevelClass; 
we .hInstance = hinst; 


(continued) 
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Figure 7-8. continued 


we. lpfnWndProc = TopLevelWndFn; 

we .hCursor ; = LoadCursor( 0, IDC_ARROW ); 

we. hIcon = LoadIcon(.0, IDI_APPLICATION ); 
wc. lpszMenuName = NULL; 

we. hbrBackground = COLOR_WINDOW+1 ; 

we. style = CS_HREDRAW | CS_VREDRAW; 
we.cbhClsExtra = 0; 

we.cbWndExtra = 0; 


if( !RegisterClass( &we ) ) 
return 0; /* return 0 if unsuccessful +*/ 


} 


/* save the current instance handle in a global variable */ 
hIinstance = hinst; 


/* create a top-level window */ 

hWnd = CreateWindow( szTopLevelClass, 
szAppTitle, 
WS_OVERLAPPEDWINDOW, 
CW_USEDEFAULT, 0, 300, 320, 
0, 
0, 
hInstance, 
NULL ); 


/* create an owner-draw listbox */ 
hListBox = CreateWindow( "ListBox", 
yee 
? 
WS_CHILD } WS_VISIBLE ! WS_BORDER | WS_VSCROLL } 
LBS_OWNERDRAWFIXED, 
16, 16, 256, 256, 
hWnd, 
IDLISTBOX, 
hInstance, 
NULL ); >" 


for( n=0; n<IMAX; n++ ) 
{ 
1RVal = SendMessage( hListBox, LB_ADDSTRING, 0, (LONG)n ); 
i£f(.1RVal < 0) 
break; 


(continued) 
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Figure 7-8. continued 


ShowWindow( hWnd, nCmdShow ); 
UpdateWindow( hWnd ); 


return hWnd; 


[RHEE EER HERERO HERE EHO EER ETE R EEE EMER EHH HEHEHE REHE EEE H ESHER HHH EEE HEE 


* * 


* TopLevelWndFn 


+ 


* 


CREE EH EEE E EER EE EERE THERE THEE SHON EEE THEE PEER EET EREE EOE EERE HEHEHE HERE EEE ® / 


LONG PASCAL FAR 
TopLevelWndFn( HWND hWnd, WORD wMsg, WORD wParam, LONG lParam ) 


{ 
LONG 1RVal = OL; 


BOOL bDWP = FALSE; 


switch ( wMsg ) 


{ 
case WM_DRAWITEM: 
MsgDrawItem( hWnd, (LPDRAWITEMSTRUCT) lParam ); 


break; 


case WM_SETFOCUS: 
SetFocus( GetDlgItem( hWnd, IDLISTBOX ) ); 
break; 


case WM_DESTROY: 
PostQuitMessage( 0 ); 
break; 

default: 
DDWP = TRUE; 
break; 


} 


if( bDWP ) 
1RVal = DefWindowProc( hWnd, wMsg, wParam, lParam ); 


return LRVal; 


(continued) 
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Figure 7-8. continued 


[REE EERE EERE H EEE EERE SEHR EERE REE ER EEE EERE REE EE EEE RHEE EERE REPRE EEE HEE 
ri 


* 


* MsgDrawltem 


* 


* 


* 


PHRHEE EEE REE EE EEE EEE E ERE E REET EERE EHR EE REET EERE EERE EERE ERE R EEE R ER ERR REE EE | 


static void MsgDrawItem( HWND hWnd, LPDRAWITEMSTRUCT lpDIS ) 


{ 
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char szBuf [32]; 


/* if necessary, redraw the entire item */ 
if( ODA_DRAWENTIRE & lpDIS->itemAction ) 


{ 


} 


/* clear the item rectangle */ 

PatBlt( lpDIS->hDC, 
lpDIS->rcItem.left, lpDIS->rcItem.top, 
lpDIS~->rcItem.right - lpDIS~>rcItem.left, 
lpDIS->reItem.bottom ~ lpDIS~>rcItem.top, 
PATCOPY ); 


/* draw the output item */ 
wsprintf£( szBuf, "This is item %ld", lpDIS->itemData ); 
TextOut ( LpDIS->hDC, 
lpDIS->reItem.left, lpDIS->rcItem.top, 
szBuf, lstrlen(szBuf) ); 


/* invert the item rectangle if the item is selected */ 
if( ODS_SELECTED & lpDIS->itemState ) 
PatBlt( lpDIS->hDC, 
lpDIS->reItem.left, lpDIS->rcItem.top, 
lpDIS->rcItem.right ~- lpDIS->rcItem.left, 
lpDIS->rcItem.bottom ~- lpDIS->rceItem.top, 
DSTINVERT ); 


/* draw a focus rectangle if the item has the input focus~*/ 


if( ODS_FOCUS & lpDIS->itemState ) 
DrawFocusRect ( lpDIS->hDC, &lpDIS->rcItem ); 


else 


{ 


/* invert the item if the selection state is changing */ 


if( ODA_SELECT & lpDIS->itemAction ) 
PatBlt ( lpDIS->hDC, 
lpDIS->rceItem. left, lpDIS->rcItem.top, 
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Figure 7-8. continued 


lpDIS->reItem. right - lpDIS->rcItem. left, 
lpDIS->rcItem. bottom -. 1lpDIS->rcItem.top, 
DSTINVERT ); 


/* redraw a focus rectangle if the focus state is changing */ 
if( ODA_FOCUS & lpDIS->itemAction ) 
DrawFocusRect( lpDIS->hDC, &lpDIS->rcItem ); 


FPRAMOHEERE EE EE AHHH EERE HEEEEEEHAEEEHHEEHEE EHS EHAEHHEREEHHER HEE TEASERS ENE RE EH 


° 2 
’ 


; ODLB.DEF module-definition file : 
. * 
PRSHHREREH EERE EEEEOEHAEEHEEER EHH HEHEHE HE HREES EH EEE HEE HEHEHE EEHREE HAE EE HH REED 
NAME ODLB 

DESCRIPTION ‘ODLB.EXE version 1.0' 

EXETYPE WINDOWS 

STUB ‘WINSTUB.EXE' 

CODE MOVEABLE LOADONCALL DISCARDABLE 

DATA MOVEABLE MULTIPLE PRELOAD 

SEGMENTS __TEXT | MOVEABLE PRELOAD DISCARDABLE 

HEAPSIZE 1024 

STACKSIZE 5120 

EXPORTS TopLevelWndFn 


Using System Commands 


The WM_SYSCOMMAND message is a general-purpose message that Windows 
uses to change a window’s size or position. Windows sends a window a 
WM_SYSCOMMAND message when you select the Restore, Move, Size, Mini- 
mize, Maximize, or Close command from the window’s system menu. Windows 
also sends WM_SYSCOMMAND when you click the mouse in the window’s 
non-client area or when you use key combinations such as Alt-Spacebar to select 
a menu or Alt-Esc to switch between application windows. 
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Message Subtype 
(wParam) 


SC_SIZE 


SC_MOVE 


SC_MAXIMIZE 


SC_MINIMIZE 
SC_NEXTWINDOW 


SC_CLOSE 
SC_VSCROLL 


SC_HSCROLL 
SC_MOUSEMENU 


SC_KEYMENU 
SC_RESTORE 


SC_TASKLIST 


Figure 7-9. 
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Corresponding 
System-Menu 
Selection, 
Keypress, or 
Mouse Action 


Size 


Move 


Maximize 


Minimize 

Alt-Esc (activate next 
window) 

Close 


Click on vertical scroll 
bar 


Click on horizontal 
scroll bar 


Click on control-menu 
box 


Alt-Spacebar 
Restore 


Ctrl-Esc (display ‘“‘Task 
List” window) 


Parameters 


Bits 0-3 of wParam: 

0: use keyboard to size the 
window 

: mouse on left border 

: mouse on right border 
mouse on top border 

mouse on upper left corner 

: Mouse on upper right corner 
: mouse on bottom border 

: mouse on lower left corner 

: mouse on lower right corner 


SAAN RY o 


Bits 0-3 of wParam: 

0: use keyboard to move the 
window 

2: use mouse to move the window 


Bits 0-3 of wParam: 
2: mouse double-click on title bar 


Bits 0-3 of wParam: 
3: mouse on control-menu box 


Bits 0-3 of wParam: 
2: mouse double-click on title bar 


lParam: 
Cursor position as 
MAKELONGG,y) or OL 


WM_SYSCOMMAND message types in wParam. Bits 4-15 of wParam contain 
the message subtype. Bits 0-3 of wParam can contain a mouse hit-test code. 
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WM_SYSCOMMAND Subtypes 


Windows 3.0 supports 13 message subtypes for WM_SYSCOMMAND. Each sub- 
type corresponds to a different action, as shown in Figure 7-9. The subtype 
values occupy the high-order 12 bits of wParam. In most cases, the low-order 4 
bits of wParam are unused. However, when a WM_SYSCOMMAND message is 
generated by clicking the mouse on a window’s non-client area, the low-order 4 
bits contain a non-zero hit-test code that specifies where the mouse was clicked. 
To determine the subtype of a WM_SYSCOMMAND message, examine only the 
12 high-order bits of wParam, as follows: 


if( SC_SIZE == (wParam & OxFFFO) ) 


Filtering WM_SYSCOMMAND Messages 


Most window functions pass WM_SYSCOMMAND messages to the default win- 
dow function, Def WindowProc, which does the necessary moving, resizing, and 
closing. If you process WM_SYSCOMMAND in a window function, you can alter 
the functions of a window’s system menu. For example, you can create a window 
that is always maximized by filtering the WM_SYSCOMMAND messages that 
correspond to the Minimize, Restore, Size, and Move system menu commands, as 
shown in Figure 7-10. 


LONG PASCAL FAR 
MaxedWndFn( HWND hWnd, WORD wMsg, WORD wParam, LONG lParam ) 
{ 

BOOL bDWP = FALSE; 

LONG i1RVal = OL; 


switch( wMsg ) 
{ 
case WM_SYSCOMMAND: 
switch( wParam & OxFFFO ) 
{ 
case SC_SIZE: 
case SC_MOVE: 
case SC_MINIMIZE: 
case SC_RESTORE: 
bDWP = FALSE; 
break; 


Figure 7-10. (continued) 
A window function that filters WM_SYSCOMMAND messages to keep a window 
maximized. 
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Figure 7-10. continued 


default: 
bDDWP = TRUE; 
break; 


} 


break; 
/* (other message processing) */ 
} 


if( bDWP ) 
1RVal = DefWindowProc( hWnd, wMsg, wParam, 1Param ); 


return 1RVal; 
} 


Emulating System Commands 


You can emulate the functions of a window’s system menu by synthesizing 
WM_SYSCOMMAND messages and sending them to DefWindowProc. To do 
this, send or post a WM_SYSCOMMAND message to the window, with wParam * 
set to the message subtype that corresponds to the action you want Windows to 
carry out. For the SC_MOVE and SC_SIZE subtypes, you should also set bits 0 
through 3 of wParam to indicate whether to emulate a mouse action or a key- 
board action. 


Imagine, for example, that you want to create a child-window control that can be 
moved within its parent’s client area without using a system menu, a title bar, or 
a thick frame. The way to do this is to post WM_SYSCOMMAND messages with 
the SC_MOVE type. If bits 0 through 3 contain 0 as they do in the following func- 
tion call, the default window function displays a four-arrow cursor and uses key- 
board input to move the window: 


PostMessage( hWnd, WM_SYSCOMMAND, SC_MOVE, OL ); 


If bits 0 through 3 of wParam contain the value 2, the default window function 
processes the message as if it had been generated by clicking on a window’s title 
bar so that the user can move the window by dragging it with the mouse: 


PostMessage( hWnd, WM_SYSCOMMAND, SC_MOVE i 0x0002, OL ); 


A good time to post this message is in response to a WM_SETCURSOR or 
WM_LBUTTONDOWN message, as you will see in the next source-code 
example. 
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Customizing the Non-Client Area 


Few Windows programs contain windows that paint their own non-client areas. 
For a window with a standard non-client area, the default window function Def- 
WindowProc processes the WM_SETCURSOR messages that correspond to 
mouse activity in the window’s non-client area, sends WM_SYSCOMMAND 
messages as needed for sizing and moving the window, and responds to 
WM-_NCPAINT by repainting the window’s non-client area. To customize a win- 
dow’s non-client area, your window function must process non-client area mes- 
sages that would otherwise be handled by DefWindowProc. 


The source code for ROUND.EXE, shown in Figure 7-11, illustrates some of the 
techniques involved in working with a window’s non-client area. The program 
creates a set of nine round child windows that can be moved by dragging with 
the mouse, as shown in Figure 7-12 on page 243. The round appearance is an il- 
lusion—the windows are actually rectangular windows with a rectangular non- 
client area large enough to contain a circular border. To support the illusion, the 
window function RoundWndFn hit-tests and paints its non-client area by pro- 
cessing WM_NCCALCSIZE, WM_NCPAINT, and WM_SETCURSOR messages. In 
a window that did not manage its own non-client area, these messages would 
normally be passed through to DefWindowProc. 


FEAR REET EERE EEE EEE TEESE E EER EEE G ESSE EER EE REESE SEES EEE EEE EEE EERE REE EEE EE EET 


+ * 
# NMAKE description for ROUND.EXE . 
# + 
FARAH EERE REE HERE E EEE E EERE EEE EEA O ESSERE SEER EE ESTE ESSE SEETHER EE HERE ERE EEE EH 
.c.0bj: 


cl /AM /c /G2sw /Osw /W4 /Zlp $+*.c 


ALL: round. exe 

round.obj: round.c round.h 
wndround.obj:.  owndround.c round.h 

round. res: round,re round.ico round.h 


re /r round.rc 


Figure 7-11. (continued) 
Source code for ROUND.EXE. 
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Figure 7-11. continued 


round. exe: round.obj wndround.ob3_ round,res round.def 
link /al:16 /nod /noe round wndround, , , libw mlibcew, round.def 
re round.res 


At ee 


* * 
* ROUND.C 7 
* * 
* Exports: TopLevelWndFn . * 
* * 


FERRE HEE EEEER EEE H EERE EH ER EE EEE H ERE ER EERE RRA REESE EERE EEE EERE REE EERE RE EE / 


#define NOCOMM 

#include <windows.h> 
#include "round. h" 

/*** FUNCTION PROTOTYPES «+#*/ 


LONG PASCAL FAR TopLevelWndFn( HWND, WORD, WORD, LONG ); 


static HWND Init ( HANDLE, HANDLE, int ); 


/*** GLOBAL VARIABLES ¢***/ 


char szTopLevelClass[] "Round: TopLevel" ; 
char szRoundWndClass[] = "Round:Child"; 


[REE EERE EEE EERE EERE EEE E EERE EEE EEE EEE EERE EERE E REE EERE EEE HH 


. * 
+ WinMain : Sena ae Se eet i ee be ee, ; 
* : * 


BREE EE EERE EERE EERE EERE ERE EEE EEE HERE RHE HEE EEE EEE E TEER E HERE EERE ER ESHER EER ED / 


int PASCAL 
WinMain( HANDLE hinst, HANDLE hPrevinst, LPSTR lpszCmdLine, int nCmdShow ) 
{ 
_ HWND hWnd; 
MSG msg; 


(continued) 
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Figure 7-11. continued 


7: PROBLEMS AND SOLUTIONS 


hWnd = Init( hInst, hPrevInst, nCmdShow ); 


if( 'hWnd ) 
return 0; 


while( GetMessage( &msg, 0, 0, 0) ) 


{ 


TranslateMessage( &msg ); 
DispatchMessage( &msg ); 


} 


return msg.wParam; 


[Ree R EERE EERE HERE ERE E EEA EERE EERE RETR EEE EEE EEE ESE EERE SEER EHH E EEE HEE EE ED 


* 


* Init 
* 


2 


* 


* 


FERRE ERER EEE R REE EHR EERE ERE E ARETE REET EERE REESE EHH R RT ERE REE SHREK ERE SEE E REE / 


static HWND Init( HANDLE hiInst, HANDLE hPrevInst, int nCmdShow ) 


{ 
WNDCLASS we; 
HWND hWnd, hChild; 
int n; 
char szTitle[6]; 


if( 0 == hPreviInst ) 
{ 


/* register the top-level window class */ 


we.lpszClassName 
we. hInstance 

we. lpfnWndProc 
we .hCursor 

we. .hIcon 

we. 1lpszMenuName 
we. hbrBackground 
we.style 
we.cbClsExtra 
we. cbWndExtra 


if( !RegisterClass ( 
return 0; 


szTopLevelClass; 

hIinst; 

TopLevelWndFn; 

LoadCursor( 0, IDC_ARROW }; 
LoadiIcon( hinst, "RoundIcon". ); 
NULL; 

COLOR_WINDOW+1 ; 

CS_HREDRAW | CS_VREDRAW; 

0; 

0; 


/* veturn 0 if unsuccessful */ 


(continued) 
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Figure 7-11. continued 


/* register the round ‘wandaw class */ ee 


we.lpszClassName = szRoundWndClass; 
we. hInstance = hInst; 
we. lpfnWndProc = Roun .dindFn; Had 
we .hCursor =: Loa dCursor (_ 0, mej ARROW ); 
we. hIcon 2° 0F5: 
we. 1lpszMenuName = NULL; 
we. hbrBackground = 0; 
we.style = 0; 
we.cbClsExtra = 0; 
we. cbWndExtra = 0; 
if( !RegisterClass( &we ) ) 
return 0; /* veturn 0 if unsuccessful +*/ 


} 


/* create the top-level window */ 

hWnd = CreateWindow( szTopLevelClass, 

shes "Round Windows", 
WS_OVERLAPPEDWINDOW, 
CW_USEDEFAULT, 0, 220, 240, 
0, 
0, 
hInst, 
NULL. ); 


/* create nine round child windows */ 

for( n=0; n<9; nt+ ) 

{ 

- hChild = CreateWindow( szRoundWndClass, 
aia 
WS_CHILD {| WS_VISIBLE, 
(ns3)*64412, (n/3)*64+12,. 60, 60, 
hWnd, 


wsprintf( szTitle, "%04X", hChild ); 
SetWindowText ( hChild, szTitle ); 
} Pee 


(continued) 
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Figure 7-11. continued 
/* display the top-level window +/ 


ShowWindow( hWnd, nCmdShow ); 
UpdateWindow( hWnd ); 


return hWnd; 


[RAPER EERE HERE RATER REE EH HEE E HEHE E HERE E HEHE REEF EEE HERE H HEE TERE OEE E REED 


* * 
* TopLevelWndFn . 
* * 


FHEHREH FERED HEE E ETHER EE DEERE SHORE ETHEL ESE RHEE EHH ERE HERE RH HER EEE HERES HEE EEE HHH / 


LONG PASCAL FAR 
TopLevelWndFn( HWND hWnd, WORD wMsg, WORD wParam, LONG lParam ) 
{ 
LONG 1RVal = OL; 
. BOOL BDWP = FALSE; 


switch ( wMsg ) 


{ 
case WM_DESTROY: 
PostQuitMessage( 0 ); 
break; 


default: 
bDDWP = TRUE; 


break; 


} 


if( bDWP ) 
1RVal = DefWindowProc( hWnd, wMsg, wParam, lParam ); 


return 1RVal; 


(continued) 
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Figure 7-11. continued 


[FHP EF EH RRE PERE RE STEER EE EE EEE EE ERED SE 


* 

* WNDROUND.C : 
* Exports: RoundWindF'n 02 00os ee i : 
. : . to . a 


HEEHHEREE HOH EE TREE EEE RE EEE RHE REE SHEERS OEE RES REE EHO ERE SHEETS HERR ET SERRE ET ERED / 


#define NOCOMM 
#include <windows .h> 
#include "round.h" 


/*** FUNCTION PROTOTYPES ***/ 


static void MsgPaint( HWND ); 
static void MsgNCPaint ( HWND ); 
static void DrawRoundFrame( HWND ); 


/+** GLOBAL VARIABLES ***/ 


RGB (OxFF, 0x00, 0x00) ; /* xed */ 
RGB (OxFF, OxFF, OxFF) ; /* white */ 
RGB (0x00, 0x00, OxFF) ; /* blue */ 


static DWORD dwBorderColor 
static DWORD dwFgdColor 
static DWORD dwBkgdColor 


[HERR EERE EERE REE EEE EEE EERE EERE EEE TEER EEE HER EEE RE EEE ARETE EERE EH EERE EER EEE EHR 


a» ‘ - sound * 
* RoundWndFn_ : Saas 


: PRD EHAE EERE ERED EE REE EERE SER EEE RH REE SEER RHEE ERE RRR EEE ORES HERE RESO R EES H EEE / 


LONG PASCAL FAR A 
_ RoundWndFn( HWND hWnd, WORD wMsg, WORD wParam, LONG lParam) 
{ Be sea 

LONG IRVal = 0L; 

BOOL bDWP = FALSE; 

RECT rect; ee 

HWND hParent; 

int nDiff; 


(continued) 


238 


7: PROBLEMS AND SOLUTIONS 


Figure 7-11. continued 


switch( wMsg ) 
{ 
case WM_NCCALCSIZE: 
nDiff = -3*GetSystemMetrics( SM_CXFRAME ); 
InflateRect ( (LPRECT)lParam, nDiff, nDiff ); 
break; 


case WM_PAINT: 
MsgPaint( hWnd ); 
break; 


case WM_ERASEBKGND: 
1RVal = TRUE; 
break; 


case WM_NCPAINT: 
MsgNCPaint ( hWnd ); 
break; 


case WM_SETCURSOR: 
if ( HTCLIENT != LOWORD(1Param) ) 
{ we 
switch ( HIWORD(l]Param). ) 
{ 
case WM_LBUTTONDOWN: 
PostMessage( hWnd, WM_SYSCOMMAND, SC_MOVE |} 0x0002, OL ); 
break; 


default: 
SetCursor( LoadCursor( 0, IDC_CROSS.) ); 
break; 
} 
} 


else 
bDDWP = TRUE; 


break; 


case WM.MOVE: 
GetWindowRect ( hWnd, érect); 
hParent = GetParent ( hWnd ); 
ScreenToClient( hParent, (LPPOINT) érect left); 
ScreenToClient( hParent, (LPPOINT)érect.right ); 
-InvalidateRect ( hParent, grect, TRUE); 
break; 


(continued) 
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Figure 7-11. continued 


default: 
bDWP = TRUE; 
break; 
} 


if( bDDWP } 
1RVal = DefWindowProc( hWnd, wMsg, wParam, lParam ); 


/* display the most recently moved child window last */ 


if( (WM_SYSCOMMAND == wMsg) && ((SC_MOVE | 0x0002) == 
SetWindowPos( hWnd, 1, 0, 0, 0, 0, 


wParam) ) 


SWP_NOMOVE | SWP_NOSIZE i SWP_NOREDRAW ); 


return lRVal; 


[RARER E EERE THERE EERE EEE HERE RHEE EE EEE REESE EEEE HERE E HERE EH EE REESE EES ERE REDE EE 


*- 


* MsgPaint 


* 


REHEE EERE EEE RETR E HERE EEE EE SEER E ETHER EERE EEE E RHEE EEE EE EP OEE PERE HERE TET ERE EE HEE S / 


static void MsgPaint( HWND hWnd ) 


{ 
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RDC hdc; 
PAINTSTRUCT ps; 

RECT rect; 

char szText [6] ; 


hDC = BeginPaint( hWnd, &ps ); 


/* show the window text. */ 
GetWindowText ( hWnd, szText, sizeof szText ); 
GetClientRect ( hWnd, Srect ); ae 


SetTextColor( hDC, dwFgdColor:); 
SetBkColor( hDC, dwBkgdColor ); 
DrawText ( hDC, szText, lstrlen(szText),. érect, 


DT_SINGLELINE |. DT.CENTER | DT_VCENTER ); 


EndPaint( hWnd, &ps ); 


(continued) 
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Figure 7-11. continued 


[REET EERE RRR EERE REEL EE EET TREE PEER EE EERE EEE EER EE EERE EEE EERE TEEN E EEE EER EE ED 


* * 
* MsgNCPaint * 
* * 


RORKE ERE T ER EET EEE REET EEE EERE EH EE RETR HSER E EHR ER ROPE THERESE ROR HSER EE EEE EE HE / 


static void MsgNCPaint ( HWND hWnd ) 


{ 
DrawRoundFrame( hWnd ); 
InvalidateRect ( hWnd, NULL, TRUE ); 
UpdateWindow( hWnd ); 

} 


[Pee EEE EERE EEE REESE HERE E HEE EEE ETH EEE HEHE EERE E EER EEE DEE ETON ERE EE EERE ED 


* * 
* DrawRoundFrame * 
* * 
* Note: This routine also fills the client area * 
* with the background brush. . 
* # 


FERRER ESE HERE EES EEE EEE TERE EEE H EH REE HEHE EH EO EEER EERSTE TERE ERE T EERE TERE EH / 


static void DrawRoundFrame( HWND hWnd ) 


{ 
HDC hDC; 
RECT rect; 
RBRUSH hBrush; 
HPEN hPen; 


hDC = GetWindowDC ( hWnd ) ; 
GetWindowRect ( hWnd, &rect ); 
OffsetRect( &rect, -rect.left, -rect.top ); 


/* draw a non-client ellipse */ 

hBrush = CreateSolidBrush( dwBkgdColor ); 

hBrush = SelectObject( hDC, hBrush ); 

hPen = CreatePen( PS INSIDEFRAME, 
GetSystemMetrics( SM_CXFRAME ), 
dwBorderColor-); 

hPen = SelectObject( hDC, hPen ); 


Ellipse( hDC, rect.left, rect.top, rect.right, rect bottom ); 


(continued) 
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Figure 7-11. continued 


hPen = SelectObject ( hDC, hPen ); 
DeleteObject ( hPen ); 

hBrush = SelectObject( hDC, hBrush ); 
DeleteObject ( hBrush ); 


ReleaseDC( hWnd, hDC ); 


[PAPER EERE EERE REET ERED HERE OTHE TEESE EEE HESS EER EEE EEE EHH HR ESET EE ER EEE EE EHH 


* * 
* ROUND.RC resource script . 
* * 


AEREEREPEEEEE SEES EEE S EEE ESTEE ES EEESESS TEES SEHR EHH ESET HEHEHE ERE EERE SERED / 


/* icons */ 
RoundIcon ICON round.ico 


[PERERA E EERE AREER EERE ETRE RE EERE ETHER EE EERE REDE REE EEE RES EEA REE EERE EERE EEE 


* ; : * 
*- ROUND. » 
* ; * 


SHORE E RHEE EE TENE EED EERE EEE REE E DER ESHEEREEEHEEE ESE RED HE NESE SER EHH EER EERE OREO YH / 


/* defined in WNDROUND.C */ . 
LONG PASCAL FAR RoundWndFn( HWND, WORD, WORD, LONG ); 


PRSHHAESSE HH REL HEHEHE OHEEESREREREHERERSHELESHHSESEHHEHETE HH REESE EEE EERE HTH EE 
; * 
3 ROUND.DEF module-definition file * 
: : * 
FATE AAAS O TEGO EHEREHHEEEORE SEO OHEES SHER ESHER TSET EERE TEP ESE RESEEERERAE SESE ED 
‘NAME ROUND 

DESCRIPTION ‘ROUND. EXE version 1.0' 

EXETYPE WINDOWS 


(continued) 
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Figure 7-11. continued 


STUB 'WINSTUB.EXE' 
CODE MOVEABLE LOADONCALL DISCARDABLE 
DATA MOVEABLE MULTIPLE PRELOAD 
SEGMENTS TEXT MOVEABLE PRELOAD DISCARDABLE 
HEAPSIZE 512 
STACKSIZE 5120 
EXPORTS TopLevelWndFn 
RoundWndFn 


a0 ay | aI 


Figure 7-12. 
Two instances of ROUND.EXE. Each child window displays its window handle. 


Client-Area Size 


Windows sends WM_NCCALCSIZE to a window function to obtain the bound- 
aries of the window’s client area. The non-client area lies between the rectangle 
that defines the outside of the window—that is, the window rectangle—and the 
client area. In response to WM_NCCALCSIZE, DefWindowProc uses the win- 
dow’s style to compute a client area that accommodates the window’s border, 
menus, scroll bars, and any other non-client area elements. However, in this sam- 
ple program, RoundWndFn processes WM_NCCALCSIZE explicitly by comput- 
ing a client area small enough to leave room for an ellipse with a fat border in 
the non-client area. 
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Painting 

To paint the non-client area, RoundWndFn processes the WM_NCPAINT mes- 
sage. This action consists only of drawing an ellipse whose border lies within 
the window’s non-client area. RoundWndFn takes a shortcut by relying on the 
Ellipse function (which is called by DrawRoundFrame) to paint the window’s 
client-area background at the time WM _NCPAINT is processed, so the 
WM_ERASEBKGND message can be trapped and not processed. In a different 
application, however, you may need to paint the client-area background by pass- 
ing WM_ERASEBKGND to DefWindowProc or by processing the message 
explicitly. | 


Hit Testing 


The WM_SETCURSOR case in RoundWndFn carries out hit testing for the round 
child windows. When a WM_SETCURSOR message indicates that the user has 
pressed the left mouse button in a child window’s non-client area, RoundWndFn 
sends the child window a WM_SYSCOMMAND message that causes Windows to 
let the user move the window with the mouse. 


In response to other WM_SETCURSOR messages in the non-client area, Round- 
WndFn displays a cursor whose shape depends on its position in the child win- 
dow. The hit-test code in the low-order word of /Param indicates whether the 
cursor lies in the window’s client area. If the cursor does not lie in the window’s 
client area, RoundWndFn assumes it is located over the non-client area and calls 
SetCursor to display a crosshair cursor. If the cursor does lie in the client area, 
RoundWndFn calls DefWindowProc, which displays the class cursor, the 
default arrow. 


If you use the crosshair cursor to trace the outline of the non-client area of each 
round child window, you will see that the non-client area is not round but rect- 


angular. Therefore, the hit testing in RoundWndFn isn’t really accurate. To do it 


right, you would need to examine the cursor coordinates each time the left 
mouse button is pressed in the non-client area and determine whether the cur- 
sor lies not only within the window’s non-client area but also within the elliptical 
window border. 


Overlapping and Clipping 
Although the child windows in ROUND.EXE appear round, Windows overlaps 


them and clips them as rectangular windows. You can demonstrate this by ad- 
ding the WS_CLIPSIBLINGS style to the CreateWindow call that creates the 
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round child windows. When you do this, you can see how Windows clips each 
child window by using the child’s window rectangle. The application supports 
the illusion that the child windows are round by explicitly repainting child win- 
dows rather than using the WS_CLIPSIBLINGS style. For this strategy to work, 
however, RoundWndFn must call SetWindowPos to place the most-recently ac- 
cessed child window at the end of the window manager’s list of child windows. 
This causes the most-recently accessed child window to be painted last. 


This seems straightforward, but it leads to subtle problems with hit testing and 
painting overlapping windows. You can verify this by experimenting with 
ROUND.EXE. You could attempt to remedy these problems by explicitly 
enumerating the window manager’s list of child windows and by doing your 
own hit testing and painting, but it is best to avoid such problems altogether by 
using only rectangular windows and letting the window manager do the work. 


Handling Asynchronous Events 


In any microcomputer, a variety of events occur asynchronously—that is, 
without being synchronized with whatever the CPU happens to be doing at the 
moment the event occurs. Events such as hardware timer ticks, key presses, 
mouse movements, and receipt of data through a serial communications port 
almost always occur at times when the CPU is not idle. Such events are typically 
signaled through hardware or software interrupts. The CPU processes an inter- 
rupt by transferring control to a special-purpose function called an interrupt 
handler, which carries out some specific action in response to the event. 


In Windows, nearly all asynchronous events are managed by interrupt handlers 
contained in device drivers installed at the time the Windows environment is ini- 
tialized. For example, KEYBOARD.DRV, MOUSE.DRV, and COMM.DRV contain 
interrupt handlers for the interrupts generated by keyboard, mouse, and serial 
communications activity. Although such device drivers take care of the vast ma- 
jority of asynchronous events, there are situations in which an application or a 
DLL must handle asynchronous events on its own. A typical example is a DLL 
that uses the NetBIOS local-area network communications interface. 


NetBIOS in Windows 


NetBIOS is a protocol developed by IBM for communicating on local-area net- 
works. NetBIOS is supported by a number of software vendors, including IBM, 
Microsoft, and Novell. Programs running in MS-DOS, OS/2, and Windows can 
use NetBIOS to communicate across local-area networks. The next few para- 
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graphs describe how to access NetBIOS in a Windows program. If you aren't 
already familiar with the NetBIOS protocol, you can find it described in IBM’s 
LAN Technical Reference manual (document #SC30-3383) as well as in a number 
of books on local-area network programming. 


To execute a NetBIOS command, you first initialize a data structure called a Net- 
work Control Block (NCB) with a predefined set of parameters, as shown in 
Figure 7-13. You then pass the NCB’s address to NetBIOS, which carries out the 
command. In a non-Windows program running under MS-DOS, you call Net- 
BIOS by placing the address of an NCB in registers ES and BX and executing 
software interrupt 5CH. In Windows, you call an API function, NetBIOSCall, in- 
stead of executing the software interrupt, as shown in Figure 7-14. The result is 
the same: NetBIOS carries out the command and returns control to the calling 


program. 

typedef struct /* NetBIOS control block */ 

{ 
BYTE cCommand; /* command code */ 
BYTE cRetcode; /* return code */ 
BYTE cLSN; /* local session number */ 
BYTE cNum; /* number of name in local name table */ 
LPSTR I1pBuffer; /* message buffer address */ 
WORD wLength; /* message buffer length */ 
BYTE cCallName[16]; /* local or remote NetBIOS name */ 
BYTE cName [16] ; /* local NetBIOS name */ 
BYTE cRTO; /* receive timeout count */ 
BYTE cSTO; /* send timeout count */ 
FARPROC fnPost; /* address of post routine */ 
BYTE cAdapterNum; /* O=1st adapter; 1=2nd adapter */ 
BYTE cCmdCplt ; /* command status */ 
BYTE cReserved[14]; /* reserved area */ 

} 

NCB; 
Figure 7-13. 


A C-language declaration for a NetBIOS Network Control Block (NCB). 


Because network data transmissions can take several seconds to execute, Net- 
BIOS lets an application initiate network transactions without waiting for them to 
complete. When a prolonged network transaction completes, NetBIOS notifies 
the program by calling a post routine, a user-defined function whose address is 
passed to NetBIOS by the program when it initiates a transaction. 
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_NETInt 


Caller: ; 
int PASCAL FAR _NETInt( NCB FAR * 1pNCB ); 


i a eS eT Ty 


EXTRN NETBIOSCALL: far 


PUBLIC _NETINT 


_NETINT PROC far 
push bp 
mov bp, sp 
les bx, [bp+6] ; ES:BX -> NCB 


call NETBIOSCALL 


xor ah, ah ; AX = return value 
pop bp 
ret 4 

_NETINT ENDP 


Figure 7-14. 
Using NetBIOSCall in Windows version 3. 


Consider, for example, how a Windows program might use NetBIOS to receive a 
packet of data from another computer on a local-area network. The program ini- 
tiates the process of receiving a packet of data by calling the NetBIOS 
NCB.RECEIVE command. The NCB used for this call contains the address of a 
post routine and the address of a buffer to be used to contain the received data. 
NetBIOS processes the NCB.RECEIVE command by starting to wait for a data 
packet. The call to NetBIOS returns immediately, so the program can continue 
executing while NetBIOS waits for data to arrive. Later, when the data has been 
received, NetBIOS calls the post routine to notify the program that the received 
data is available. 


An Asynchronous-Event Handler 


The key to writing a NetBIOS post routine is to realize that the event that triggers 
a call to the routine occurs asynchronously, outside of Windows’ multitasking 
and message-processing mechanisms. In order for the post routine to work, it 
must notify a Windows program that an event has occurred without disrupting 
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program task management or message flow. To accomplish this, the post routine 
must place a message into an application’s message queue with a call to 
PostMessage or PostAppMessage. 


The source code in Figure 7-15 contains a post routine, _NCBPost, that demon- 
strates how this can be done. When NetBIOS calls _NCBPost, registers ES:BX 
contain a pointer to the NCB whose processing has just been completed. The 
_NCBPost routine passes this pointer to Post NCBMessage, which uses the pointer 
to obtain a window handle from a static table. PostNCBMessage then calls 
PostMessage, which places a user-defined message into the appropriate message 
queue. In this way, the asynchronously executed post routine notifies an applica- 
tion that NetBIOS processing for the NCB has completed. 


; This routine calls a C function defined as: 

; void PASCAL FAR PostNCBMsg(NCB FAR * 1pNCB, int nCompletionCode) 
, 4 

; PostMessage( ... ); 

er 


EXTRN POSTNCBMSG: far 


PUBLIC _NCBPOST 


_NCBPOST PROC far ; at entry: AL = completion code 
7 AH = 0 
; ES : BX->NCB 
pusha ; save all registers 
push es ; push NCB address 
push bx 
push ax ; push completion code 


call POSTNCBMSG ; call C routine 
; to call PostMessage 


popa ' > xestore all registers 
iret ; return to NetBIOS 


_NCBPOST ENDP 


Figure 7-15. 
Source code for a NetBIOS post routine for Windows version 3. 
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The reason this design works is that PostMessage is re-entrant—that is, if Net- 
BIOS happens to call _NCBPost at a moment when Windows is executing 
PostMessage, _NCBPost’s own call to PostMessage will execute properly without 
disrupting the previous call to PostMessage. PostMessage and PostAppMessage 
are the only functions in the Windows API that are guaranteed to be re-entrant, 
so they are the only API functions that are safe to call in an asynchronously exe- 
cuted routine such as _NCBPost. This is the technique to use when you write 
your own asynchronous-event handler. 


A Quick Exit 


In some settings, a Windows user may find it convenient to be able to exit 
quickly from the Windows environment without switching to a shell application 
such as the Program Manager. To do this, use the ExitWindows API function to 
terminate all applications cleanly and exit from the Windows environment. The 
sample program in Figure 7-16 shows how to use ExitWindows in this way. The 
application displays an icon that you can click with the mouse or select by press- 
ing Alt-Spacebar to terminate a Windows session. 


PHAR E HEH EEEE REE ERE EERE HEHE EEE EERE HE EEE EEE EEE EE EERE HERE ETHERS HERE THERE EES ® 


# * 
# NMAKE description for WINEXIT.EXE 7 
# * 


PEAKE RHEE RE EERE EEE H THERE EERE EEE TREE EERE EE EEE E HERES PEE EH ESTER EEE E EE HE EE EE 


.c.0bj: 
cl /AM /c /G2sw /Osw /W4 /Z1p $*.c 


ALL: winexit.exe 
winexit.obj: winexit.c 
winexit.res: winexit.rc winexit.ico 


re /r winexit.rc 
winexit .exe: winexit,obj winexit .res winexit .def 


link /al:16 /nod /noe winexit, , , libw mlibcew, winexit.def 
re winexit.res 


Figure 7-16. (continued) 
Source code for WINEXIT.EXE 
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Figure 7-16. continued 


[HERE EEER ETHER HEHE EERE RE EE EEE E HE ERE EE EERE THEE EERE E EER EEE REESE EEE ERE E ER EE 


* 3 * 

* WINEXIT.C : 

* . ¢ 
* Exports: TopLevelWndFn ide 
+ : 


PEHREEE EEE HE REED ERE EEE H REET ERE EHH EEE HERE EH EEE EERE E ES EERE TESTE TERRE REE E EE / 


#define NOCOMM 

#tinclude <windows.h> 

/*** FUNCTION PROTOTYPES ***/ 

LONG PASCAL FAR TopLevelWndFn( HWND, WORD, WORD, LONG ); 
static HWND Init ( HANDLE, HANDLE, int ); 

static BOOL QueryExit ( HWND ); 

/*** GLOBAL VARIABLES .**+*/ 


char szTopLevelClass[] = "WinExit : TopLevel"; 


[PARRA REO O TERE EAE O HERE E ER ERE EERE EE ERE EERE EEE E RHEE EEE EE ERE RE SERRE EEE E EEE HE 


* pean states ee * 
* WinMain : : * 
* ae oS a : * 


CORRE EERE EEE ER ADHERE ERE H EEE E EH ERE RHETT ERE EER OEHHA EERE SORTER REDE REE REESE EEE E ES / 


int PASCAL eg ; 
WinMain( HANDLE hInst, HANDLE hPrevInst, LPSTR lpszCmdLine, int nCmdShow ) 
{ene 

HWND = ohWnd; 

MSG msg; 


hWnd = Init ( hiInst, hPrevinst, nCmdShow ); 
if( !hwWnd:) 
return 0; 


(continued) 
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Figure 7-16. continued 


while( GetMessage( &msg, 0, 0, 0 ) ) 


{ 
TranslateMessage( &msg ); 


DispatchMessage( &msg ); 
} 


return msg.wParam; 


[RARE EEE HERE EERE ESHER ET EEE RETR E HERE EERE PEER EEE HERE E THEE EEE HEED EEE EEE 


* * 
* Init * 
* * 


PEERED ERE REE EOE E EATER EEE E REE EET TEETH EEE REE THERE EERE REE ER ERR ERE E RHEE EET / 


static HWND Init( HANDLE hInst, HANDLE hPrevinst, int nCmdShow ) 
{ 

WNDCLASS wc; 

HWND hWnd = 0; 


/* allow only one instance */ 
if( hPrevInst ) 
return 0; 


/* register the top-level window */ 


we .lpszClassName = szTopLevelClass; 

we. hInstance = hInst; 

we. lpfnWndProc — = TopLevelWndFn; 

we .hCursor = LoadCursor( 0, IDC_ARROW ); 

we. hicon = LoadiIcon( hInst, "TopLevelIcon" ); 
we.lpszMenuName = NULL; 

we .hbrBackground = COLOR_WINDOW#1 ; 

we.style = 0L; 

wo,cbClsExtra = 0; 

we, cbWndExtra = 0; 


if( !RegisterClass( &we ) ) 
return 0; 


/* create the top-level window */ 

hWnd = CreateWindow( szTopLevelClass, 
"Windows Exit", 
WS_OVERLAPPEDWINDOW i WS_ICONIC, 
0, 0, 0, 0, 


(continued) 
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Figure 7-16. continued 


0, 
OSes 
neces 
hier 


/* put window on screen +f 
ShowWindow( hWnd, SW |_SHOWMINNOACTIVE 
UpdateWindow( hWnd ); 


return hWnd; 


[PEER EERE TREE EEE EEE ERE EERE REESE RSE HERES EEE REE EERA REESE EERE EREOEH REE EEE EE EES 


* TopLevelWndFn 


* 


* 


FORE RER EERE EE HERE REE REDE ER EEE ERE PEE EREEE EEE EEE EEE EE HERE EHH E REESE ERE R FERRE ERE f 


beh LONG PASCAL FAR 
TopLevelWndFn( HWND hWnd, WORD wMsg, WORD wParam, LONG 1Param ) 
{ 
LONG 1RVal = OL; 
- BOOL bDWP = FALSE; 


switch( wMsg ) 
{ 
case WM_QUERYOPEN: 
break; 


-. ease WM_DESTROY: 
PostQuitMessage( 0 ); 
break; 


case WM_NCLBUTTONDOWN: © 
QueryExit ( hWnd de 
break; 


case WM_SYSCHAR: 
aan wParam) 
(5 
case VK_SPACE: Ree Ret eect cae 
if ( 0x20000000L & param ) _/* Alt-Spacebar */ 
gueryExit (|: ‘hWnd Le) a Ral cane eee 
break; 
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Figure 7-16. continued 


case VK_RETURN: “J* Enter */ 
QueryExit ( hWnd ); 
break; 


} 

break; 
default: 

bDWP = TRUE; 


break; 


} 


if( DDWP ) 
1RVal = DefWindowProc( hWnd, wMsg, wParam, lParam )/; 


return 1RVal; 


[PERRET REET EERE TERE EERE EERE EEE TEE EEE TEREST ESE E PETE SEE ER HEHEHE RESET EEE EH 


* 


* 


* QueryExit + 


+ 


* 


FERRE EREE ERE EEER EERE E TEER EE REESE HERES HERES PEER EERE EERE TORRE RHEE EERE EERE ED / 


static BOOL QueryExit ( HWND hWnd ) 


{ 


BOOL  bRVal = TRUE; 


if( IDOK == MessageBox( hWnd, 
"This will end your Windows session.", 
"End Session", 
MB_OKCANCEL i. MB_ICONEXCLAMATION 

MB_SYSTEMMODAL ) ) 

{ 

bRVal = ExitWindows( OL, 0 ); 

} 


return bRVal; 


(continued) 
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Figure 7-16. continued 


[PERE eRe E EEE EEE EER ERE REDEEM REE OEE REE ER EEE EERE PETE ETHER EEE ERE R EOE EEE OD 


* WINEXIT.RC resource script =#=§= * 
. Sco ht eee ; 


HEHEHE REEP ESTEE E DPE E EEE REE EERE EEE EH ERM HEHE REET TREE O HERE EEE e HEE ER EEE / 


/* icons */ 


TopLeveliIcon ICON winexit.ico 

PRAHHEREEHE SAREE HREEHEHEREEEHHERE EEE REE HHEEEEHEREEEHEEREHERE HEHEHE EERE EE EHH DEH 

. * 

, 

; WINEXIT.DEF module-definition file * 
* 


. 
, 
PEER EAHEREEE SE REEE HERR EEE EEE EEE ET EEEEEREHEHEREGHE REET HHA EE HAE REESE EE EHD HOHE EE 


NAME = WINEXIT 
DESCRIPTION ‘WINEXIT.EXE version 1.0' 
EXETYPE WINDOWS 
STUB 'WINSTUB.EXE! 
CODE MOVEABLE PRELOAD DISCARDABLE 
DATA MOVEABLE SINGLE PRELOAD 
HEAPSIZE 512 
STACKSIZE 5120 
EXPORTS TopLevelWndFn 
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386 enhanced mode. See Enhanced mode. 
API. See Application program interface. 


Application program interface (API). Windows’ API contains more than 600 
function calls that support I/O, manage memory resources, allow multitasked 
applications to execute cooperatively, and provide a variety of other services. 


Atom. In Windows, an atom is a data string identified by a unique integer value. 
Windows provides an atom-management API for atoms stored in a program’s 
local heap as well as for atoms stored globally. 


Automatic data segment. See Default data segment. 
DDE. Dynamic Data Exchange. 


Default data segment. A data segment, associated with an application or a 
dynamic link library, that can contain static data, a stack, and a local heap. In 
an assembly-language program, the default data segment is named _DATA 
and is part of group DGROUP. In a C program, the Microsoft C compiler takes 
care of naming and grouping the default data segment. 


Dereference. To convert an indirect reference to a direct reference. For ex- 
ample, the Windows API function GlobalLock dereferences a memory handle 
by returning a physical address that can be used to reference the memory 
block identified by the handle. 
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Device. A video display, printer, disk drive, or other hardware used for input or 
output. 


Device driver. A low-level software interface to a specific hardware device. In 
Windows, device drivers are usually implemented as DLLs with the filename 
extension .DRV. A typical Windows installation includes device drivers that 
support the video display, mouse, keyboard, serial communications port, and 
printer. 


DLL. See Dynamic link library. 


Dynamic link library (DLL). A windows module containing executable code 
and data that can be referenced by Windows applications or by functions in 
other DLLs. Functions and data in a DLL are dynamically linked to the func- 
tions that reference them—that is, the links are made at runtime when the li- 
brary is loaded or later. 


Enhanced mode. A Windows operating mode in which Windows’ memory 
manager uses virtual memory to manage the global heap. In enhanced mode, 
Windows applications run in 16-bit protected mode and non-Windows appli- 
cations run in virtual 8086 mode. Also, in enhanced mode, Windows applica- 
tions share access to hardware devices and local area networks through 
virtual devices that run in 32-bit protected mode. Supported on 80386 and 
80486 microprocessors. 


Entry point. The logical start of an executable function. In Windows, function 
entry points can be identified by ordinal number as well as by name. 


Expanded memory. See LIM EMS. 


Extended memory. Memory whose physical addresses lie above 1 MB. Ex- 
tended memory is addressable only in protected mode on 80286, 80386, or 
80486 microprocessors. Windows uses extended memory in standard and en- 
hanced CPU modes. 


Far pointer. A far pointer specifies a memory address as a 32-bit value that 
designates both a particular segment in memory and an offset within that seg- 
ment. See also Near pointer. 


GDI. See Graphics Device Interface. 


Graphics Device Interface (GDI). The Graphics Device Interface is a set of 
Windows API functions that support graphical output to the video display and 
to a variety of printers and plotters. 
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Handle. An arbitrary numeric value assigned by Windows to let an application 
identify a certain item. Windows uses handles to identify a variety of items, in- 
cluding modules, instances, windows, memory blocks, and GDI objects. 


Hash table. A table of values in which data items are scattered according to a 
formula that allows the table to be quickly searched for a particular value. 
Windows uses hash tables to store data such as the string values associated 
with local or global atoms. 


Heap. An area of memory reserved for dynamic allocation of memory blocks, 
organized in a tree structure that facilitates sorting and searching. Windows 
manages all available memory as a global heap. Windows’ memory manager 
also supports a local heap in the default data segment of each module in 
memory. 


Instance. In Windows, one of many possible copies of an independently loaded 
module. Windows can load multiple instances of an application but only one 
instance of a DLL. 


Instance thunk. A short piece of executable code that sets the default data seg- 
ment for an exported far function before the function executes. 


LIM EMS. The Lotus-Intel-Microsoft Expanded Memory Specification describes 
an industry-standard hardware and software interface to bank-switched (ex- 
panded) memory for computers running MS-DOS. Windows’ memory man- 
ager provides applications with transparent access to expanded memory using 
version 4.0 of this standard. 


Linker. A utility program such as Microsoft’s LINK.EXE that combines compiled 
or assembled object (.OBJ) files and a module-definition (DEF) file into an 
application (.EXE) file or a dynamic link library (DLL) file. 


Linking. The process of resolving a program module’s external references (ref- 
erences to functions or data in other program modules). Dynamic linking oc- 
curs during or after the time a program is loaded into memory to be executed. 
Static linking, which is performed by a linker such as Microsoft’s LINK.EXE, 
occurs prior to the time a program is loaded. 


Loading. The process of copying a module’s executable code and data from a 
file into memory. If the module represents a Windows application, loading 
allows Windows to begin executing the application. If the module represents 
a dynamic link library, loading allows the library’s functions and data to be 
accessed by other programs. 
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Memory model. A description of the layout of executable code and data in 
memory. Windows programs generally use either a small or a medium 
memory model. Both small-model and medium-model programs use one data 
segment; small-model programs use one code segment and medium-model 
programs can use multiple code segments. With the Microsoft C compiler, you 
can select a program’s memory model by using the /AS (small-model) or /AM 
(medium-model) switch. 


Module. A collection of executable code and data that Windows can load into 
memory. A Windows module must be contained in an executable (.EXE) file 
or a dynamic link library file, and the name of the file must be the same as the 
name in the NAME or LIBRARY statement in the module-definition (.DEF) file 
used to link the module. 


Module-definition file. The statements in a module-definition (DEF) file 
specify a module’s name, type (application or library), segment usage, and im- 
ported or exported functions. A linker such as Microsoft’s LINK.EXE uses the 
information in the module-definition file to build segment-loading and 
dynamic-linking information into a module’s loadable .EXE or .DLL file. 


Near pointer. A near pointer specifies a memory address as a 16-bit value that 
represents an offset within a module’s default data segment. See also Far 
pointer. 


OEM. Original Equipment Manufacturer—that is, the manufacturer of the com- 
puter hardware on which Windows software is running. In particular, the 
“OEM character set” is the character set used in the computer’s keyboard and 
video-display subsystem. 


Post. In Windows, to post a message is to place it in an application’s message 
queue, using PostMessage or PostAppMessage, rather than directly calling an 
application’s window function by using SendMessage. 


Private data. Data that can be accessed only by a particular function. 


Private dynamic link library. A dynamic link library designed to be used by 
only one application. To designate a DLL as private, use the /P switch with the 
resource compiler, RC.EXE. 


Protected mode. A CPU addressing mode in which the CPU protects memory 
by preventing programs from erroneously accessing blocks of memory that 
belong to other programs. In 16-bit protected mode (supported on the 80286, 
80386, and 80486 microprocessors), the CPU can directly address a total of 
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16 MB of memory, and a memory address consists of a 16-bit selector and a 16- 
bit offset. In 32-bit protected mode (80386 and 80486), the CPU can directly 
address a total of 4 GB of memory, and memory addresses are 32-bit values. 


Real mode. A CPU addressing mode and a Windows operating mode in which a 
total of 1 MB of memory is directly addressable. In real mode, a memory ad- 
dress consists of a 16-bit segment and a 16-bit offset. Real mode is supported 
on all microprocessors in the Intel 8086 family. See also Enhanced mode, 
Standard mode. 


Resource. A set of one or more dynamically loadable data items. In Windows, 
resources are stored as part of executable program (.EXE) files or dynamic 
link library files. Windows’ resource compiler translates programmer-defined 
resource definitions (.RC file) into a binary format (.RES file) and subsequently 
adds the binary resources to a specified executable or library file. 


Resource-definition file. The statements in a resource-definition (.RC) file de- 
scribe a module’s dynamically loadable resources, including menus, dialog 
boxes, and icons. A resource compiler compiles the statements in the .RC file 
to a binary format (.RES file); the binary resources can then be merged into 
the module’s loadable .EXE or library file. 


Scaffolding. Source code added to a program specifically to support application 
development or debugging. 


SDK. Software Development Kit. 


Send. In Windows, to send a message is to call a window function directly, 
using SendMessage, instead of placing the message in an application’s message 
queue, using PostMessage or PostAppMessage. 


Standard mode. A Windows operating mode in which Windows applications 
run in 16-bit protected mode on an 80286, 80386, or 80486 microprocessor. 


Task. One of several concurrently executing programs. In Windows, tasks are 
executed cooperatively—that is, each task periodically transfers control to 
Windows’ task manager to let other tasks execute in turn. 


Thunk. A short piece of executable code, compiled dynamically by Windows at 
the time a program is loaded or executed, that performs some simple function 
on Windows’ behalf. See also Instance thunk. 


Virtual 8086 mode. A CPU addressing mode in which an 80386 or 80486 mi- 
croprocessor emulates 8086 real-mode addressing. The microprocessor can 
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concurrently support multiple virtual 8086 sessions. Windows uses virtual 
8086 sessions when operating in enhanced mode to execute non-Windows 
MS-DOS applications. 


Virtual memory. A memory-management technique in which data in physical 
memory can be swapped to disk. The use of virtual memory provides pro- 
grams with more memory storage and a larger range of memory addresses 
than could be supported in physical memory alone. Windows’ memory man- 
ager supports virtual memory when running in enhanced mode on an 80386 
or 80486 microprocessor. 


Windows application. An executable program designed to run in the Windows 
environment. 
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AddAtom, 147 
Add Custom Control command, 126 
/AM compiler switch, 33 | 
Application program interface (APD 
debugging and, 40-43 
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modules and, 4, 5 
overview, 3, 255 
applications. See also particular 
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DLLs vs., 61, 75 
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sharing data between (see DDE) 
structure of, 13-26 
ASCII, Clipboard data format, 171 
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techniques involving, 245—49 
atoms, 147, 167—68, 255 
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automatic variables, debugging and, 45, 
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bitmaps, 12, 171 
breakpoints. See debugging 
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bugs. See debugging 
Button control class, 85, 105 
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C language, 33 
C++ language, 156 
callback function, 187—96 
CallWindowProc, 138, 156 
CB_INSERTSTRING, 222 
cfFormat, 171 
classes, object-oriented programming, 
139-43 
clients, DDE, 160 
Clipboard 
data formats, 171, 200-201 
data transfer and, 159 
Close command, 230 
CodeView program 
message tracing and, 39 
overview, 31-32 
scaffolding and, 38 
trapping wild pointers and, 54-55 
.COD files, 34 
/CO linker switch, 32 
color, module for, 5 
COLOR_BACKGROUND, 44 
ColorCtl custom control class, 105-28, 
131-32 
ColorCtlDigFn, 126, 128 
COLORCTL.DLL, 105-28 
ColorCtlFlags, 126, 128 
ColorCtlInfo, 126 
ColorCtiStyle, 126, 127 
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ColorCtlWndFn, 126 
COLOR_WINDOW, 44 
ComboBox control class, 85 
commands. See also particular 
command 

in DDE, 164, 198-99, 201 

system, 229-32 
Command Status data items, 202 
COMM.DRV module, 5 
communications, module for, 5 
controls 

custom (see custom control classes) 

handles for, 11-12 

owner-draw, 221-29 

predefined classes, 85 

programming techniques involving, 

207-29 

conversations, DDE 

described, 159-61 

initiating in DDEML, 196—98 

managing, 176, 182-83 
CONVINFO, 198 
cooperative multitasking, 6 
CPU modes, bug-proofing and, 56-57 
CreateBitmap, 167 
CreateCompatibleBitmap, 167 
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in custom controls and, 85, 104, 207 

in debugging, 44, 53-54 
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in object-oriented programming, 140, 


143 
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controlling, 5, 147-48 
handles for, 12 
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custom control classes, Dialog Editor 
and, continued 
Info function, 105, 126 
initialization and class registration, 
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overview, 104—6 
sample code, 106-25 
Style function, 105, 127, 128 
window function, 126 
in DLLs, 85, 95-104 
examples, 85-95, 96-104 
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testing and debugging, 85 
using, 104 
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confusing static and automatic, 44-45 
corruption via wild pointers, 55 
objects and, 143-47 
sharing in DLLs, 77-79 
transfer (see DDE) 
data formats, DDE and, 171 
Data Interchange Format (DIF), 171 
data segment(s) 
dissociated, 49-51 
DLLs and, 70-71, 74-76 
register, 49, 73, 75 
/D compiler switch, 38 
DDE (Dynamic Data Exchange) 
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DDE) 
data formats, 171 
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flags, 168-71 
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Management Library (see DDEML) 
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DDE (Dynamic Data Exchange), 
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shareable global memory, 166-67, 169 
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windows and, 9 
DdeAbandontTransaction, 177, 185 
DdeAccessData, 179, 187 
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DDEADVISE, 166, 168-71 
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DdeConnect, 176, 182, 196, 198 
DdeConnectList, 176, 182, 196, 198 
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DdeCreateStringHandle, 178, 186 
DDEDATA, 166-67, 168-71 
DdeDisconnect, 176, 183 
DdeDisconnectList, 176, 183 
DdeEnableCallback, 177, 185-86 
DdeFreeDataHandle, 179, 187 
DdeFreeStringHandle, 178, 186 
DdeGetData, 179, 187 
_ DdeGetLastError, 175, 182 
DdelInitialize, 175, 180, 181, 193 
DdeKeepStringHandle, 178, 186 
DDEML (DDE Management Library) 
API functions 
conversation management, 176, 
182-83 
interface management, 175, 180-82 
memory management, 179, 187 
string management, 178, 186 
transaction management, 177-78, 
183-86 
callback function, 187-96 
establishing data link, 198 
executing commands, 198-99 
initiating a conversation, 196—98 
overview, 159, 172-74 
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sending data to server, 198 
transaction processing, 174-75 
DdeNameService, 176, 182 
DDEPOKE, 166-67, 168-71 
DdePostAdvise, 177, 186 
DdeQueryConvInfo, 176, 183, 196, 197 
DdeQueryNextServer, 176, 183 
DdeQueryString, 178, 186 
DdeSetUserHandle, 178, 186 
DdeUnaccessData, 179, 187 
DdeUninitialize, 175, 180, 181 
debugging 
bulletproofing, 56-58 
confusing static and automatic data, 
44—45 
fatal-exit errors, 45—46 
program design and, 29-30 
techniques, 37—43 
terminals, 30—31 
tools, 31-37 
visible bugs, 44 
wild pointers, 47-56 
DEBUG program, 32 
default data segment, 70-71, 74-76, 255 
#define directive, 38 
Def WindowProc 
in custom controls, 130 
in debugging, 44 
non-client areas and, 233, 243-45 
in object-oriented programming, 137, 
138 
system commands and, 231, 232 
in window function, 25 
descriptor tables, 51 
device drivers, modules for, 5 
dialog boxes, custom control classes 
and, 105 
DialogBoxParam, 127 
Dialog Editor program. See custom 
control classes, Dialog Editor and 
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DIF (Data Interchange Format), 171 
DISCARDABLE attribute, 70 
disks, hard, 5 
DispatchMessage, 23-24 
dissociated data segments, 49-51 
dl es WDEB386 command, 34 
DLGEDIT.C, 126 
DLLBASE.DLL, 61—67 
DLLs (dynamic link libraries) 
calling functions, 72-76 
custom controls in, 85, 95-104 
debugging and, 43 
described, 61, 256 
example, 61-68 
managing segments, 68-71 
resources and, 80-81 
sharing functions and data, 77-80 
DOS, Windows programming and, 3 
DrawFocusRect, 223 
DrawRoundFrame, 244 
DS register, 49, 73, 75 
dumb terminals, 30-31 
Dynamic Data Exchange. See DDE 
dynamic link libraries. See DLLs 


Easter, 67 

Edit control, 85, 208-12, 214-21 

Ellipse, 131 

EMS (expanded memory specification), 
yoo 

EnableWindow, 57 

encapsulization, 135 

EN_CHANGE, 130 

EndDialog, 128 

enhanced mode, 4, 5, 34, 256 

entry point, 256 

EnumWindows, 22, 26 

errors. See debugging 

events, asynchronous, 245-49 

exiting Windows 

ExitWindows, 249-54 
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exiting Windows, continued 
Windows Exit Procedure (see WEP) 

expanded memory, 3, 33, 257 

exported functions, 5 

extended memory, 3, 256 


far calls, DLL functions and, 72 
far function prologs, 72-73 
far pointers 
bugs involving, 51-54 
described, 256 
DLLs and, 75-76, 77-80 
FatalExit, 31 
fatal-exit errors, 45—46 
/Fc compiler switch, 34 
files 
.COD, 34 
handles for, 11-12 
include, 30 
symbol, 32, 34 
FindWindow, 95 
FIXED, 54, 77 
flags 
DDE and, 168-71, 191 
Flags function, 105, 127-28 
fonts, handles for, 11-12 
FreeLibrary, 67, 68 
functions. See also particular function 
or type 
described, 5 
in DLLs, 72-76, 79-80 
prototypes, 30 


GDI (graphics device interface) 
DDE and, 167 
described, 256 
handles for, 12 
module for, 5 
GetClassInfo, 140, 141, 144~—45 
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GetClassWord, 140 
GetMessage, 8, 23, 24 
GetModuleUsage, 68 
GetProcAddress, 79 
GetProp, 146, 147, 156 
GetStyleInfo, 128 
GetWindowLong, 40, 140, 142, 143 
GetWindowWord, 40, 140, 143 
GlobalAddAtom, 147, 168 
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in custom controls, 129 

in debugging, 52, 58 

in DDE, 167 

in DLLs, 70, 77 

in object-oriented programming, 144 

overview, 12, 13 
global atoms, 147, 167—68 
GlobalDeleteAtom, 168 
GlobalFindAtom, 168 
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global heap, 13 
GlobalLock, 52, 57, 12, 77, 78 
global memory 

blocks, 166-67, 169 

handles, 77—80 
GlobalReAlloc, 58, 144, 169 
GlobalUnlock, 52-53, 57, 78 
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GMEM_DDESHARE, 57, 78, 167 
GMEM_FIXED, 54 
GMEM_MOVEABLE, 54 
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graphics 

DDE and, 167 
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module for, 5 
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graphics device interface. See GDI 
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Heap Walker utility, 55, 58 
HideWaitCursor, 147-48 
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module for managing, 5 
import libraries, 43 
include files, 30 
InflateRect, 131 
Info, 105, 126-27 
Init, 22 
input. See also keyboard(s); mouse 
bulletproofing and, 57 
custom control classes and, 129 
InstallKeyTrap, 156 
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described, 5—6, 257 
handles for, 11-12 
Windows libraries and, 70 
instance thunks, 50-51, 73, 257 
intercept functions, 40-43 
interface management, DDEML, 175, 
180-82 
interrupt handlers, 245 
item names, 164—66, 199-200 
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jump tables, in DDEML callback 
functions, 192-93 
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K 
KERNEL.EXE module, 5 
keyboard(s) 
bulletproofing and, 57 
messages and, 7-8 
module for, 5 
KEYTRAP.EXE, 149-56 
KeyTrapWndFn, 156 
KRNL286.EXE module, 5 
KRNL386.EXE module, 5 
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languages, programming. See 
particular language 


LAN Technical Reference manual, 246 


LB_ADDSTRING, 222, 223 
LB_INSERTSTRING, 222 
LibEntry, 66, 70 
LibMain 
in custom controls, 96, 103, 126 
described, 61, 66 
in memory models, 70 
libraries 
custom control, 105-28 
DDE Management (see DDEML) 
dynamic link (see DLLs) 
import, 43 
library reference counts, 68 
/LI\inker switch, 33 
LIM (Lotus-Intel-Microsoft) EMS 
standard, 3 
linker, 257 
Lisp language, 145 
list-box controls, 85, 207-8, 223-29 
In command, 35 
LoadBitmap, 80 
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described, 4 
in DLLs, 67, 68, 80 
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DLLs and, 66 
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LockSegment, 71 
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Lotus-Intel-Microsoft Expanded 
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low memory, 57-58 
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/MAP linker switch, 33 
MAPSYM utility, 32, 33, 36 
Maximize command, 230 
memory 
custom control classes and, 129 
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extended, 3 
global blocks, 166-67, 169 
handles for, 11-12 
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managing 
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module for, 5 
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models, 69-70, 258 
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DDE and, 159, 160-64 
filtering, 149-56, 213-21, 231-32 
object-oriented programming and, 
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object-oriented programming, 
continued 
described, 135-36 
message passing, 136-37, 138-39 
sample programs, 147—48, 149-56 
windows as objects, 137-38 
Windows limitations, 135 
ODA_DRAWENTIRE, 222 
ODA_FOCUS, 222 
ODA_SELECT, 222 
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OVEDIT.EXE, 208-12 
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quitting Windows. See exiting Windows 
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STRINGTABLE resource, 67 
Style, 105, 127, 128 
subclasses, 140—42 
/s WDEB386 switch, 34 
/S: WDEB386 switch, 34 
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DDEML callback function and, 190 
described, 25 
object structure and, 135 
tracing messages and, 39 
symbol files, 32, 34 
Symbolic Link format, 171 
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system timer, module for, 5 
System topic, 200-201 


T 


Tagged Image File Format. See TIFF 
task manager, 5—6, 7 
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